--- title: "API Only" description: "Integrate the Fabrick Payment Orchestra services directly through the API, without Fabrick payment pages: card form on the merchant's website, wallets, alternative payment methods and token payments." url: "https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/" language: "en" --- # API Only The **API Only** integration lets you use the Fabrick Payment Orchestra services directly through the API, without relying on the payment pages developed by Fabrick. The merchant keeps full control of the checkout experience: they collect the payment details on their own pages, handle the redirects required by authentication and by alternative payment methods (APMs), and send the requests to Fabrick for processing. It is the approach suited to larger organisations that need to integrate payments with their own backend and interface, including contexts where hosted integrations are not supported, such as WebViews and native applications. > **Hosted integrations and API Only** > > Compared with the hosted integrations (Checkout Page, Pay By Link, Lightbox, Web Component), with API Only the interface, the collection of payment details and the handling of redirects are **the merchant's responsibility**. In return, you get maximum freedom to customise the flow. --- ## Use cases The API Only integration covers different scenarios, which share the same basic calls: | Scenario | How it works | Details | | ------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Card form on the merchant's website** | The merchant collects the card details with their own form and sends them to Fabrick with `payment/submit` | [Payment flow](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#payment-flow) | | **Payment with a tokenized card** | The merchant sends with `payment/submit` the token of a previously saved card, without asking the buyer for the details again | [Tokenization](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/token/) | | **Apple Pay and Google Pay in the merchant's checkout** | The merchant integrates the wallet SDKs and sends the returned payload with `payment/submit` | [Apple Pay](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/) · [Google Pay](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/) | | **Alternative payment methods (APMs)** | The merchant initialises the transaction specifying the APM in `paymentType` and redirects the buyer to the service | [Payment method presentation logic](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#payment-method-presentation-logic) | | **Recurring payments** | The merchant initialises the series with an authenticated transaction and carries out the subsequent charges with the token | [Recurring payments with cards and wallets](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/recurring-payments/) | --- ## Payment method presentation logic With the API Only integration there is no payment method selection page: it is the merchant who decides which method to use and specifies it in the calls. - **Cards and wallets**: the method is defined by the `paymentType` field of the `payment/submit` call, together with the payment details collected by the merchant (see [Sending the payment details](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#step-2--sending-the-payment-details)). - **Alternative payment methods (APMs)**: the method is defined by the **`paymentType`** field of the **`payment/create`** call, populated with the APM tag. By adding the `paymentChannel` object with `channelType` set to `LINK`, the response contains in `payload.userRedirect.href` the link to use for the buyer: if the method requires a redirect, the link takes them straight to the service; if not, the buyer completes the payment on the Fabrick page. > **API requests for APMs** > > Each alternative payment method has specific fields and rules for the API request: the request and response examples are described in the *API integration* section of the page of each method (see [Alternative payment methods](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/)). > **Mandatory and dedicated fields of individual APMs** > > Some APMs require mandatory fields in the **`payment/create`** call, which must be included to start the payment with the method specified in `paymentType`. Other dedicated fields enable specific features, for example tokenization, recurring payments or order details. The instructions are in the *API integration* section of the page of each method, for example [PayPal](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/paypal/) and [Satispay](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/satispay/). > **Full list of paymentType values** > > The possible **`paymentType`** values are listed in the [payment type codes](https://api.paymentorchestra.fabrick.com/#payment-type-codes) section. Alternatively, you can use the **`GET shop/paymentMethods`** endpoint to check in real time the payment methods enabled for the `shopLogin` used, filtering the response by `payload.paymentMethod.paymentType`. --- ## Order confirmation page and server-to-server notification When creating the request you can use the **`responseURLs`** object to dynamically define the redirect URLs and the server-to-server notification URL that the system will use at the end of the transaction, for both positive and negative outcomes. With API Only, the redirect URLs are used when the buyer returns from an external flow, such as 3DS authentication or payment on an APM. When the **`responseURLs`** object is included in the call, the system applies the URLs specified in the request **for that transaction only**, instead of those configured in the Gestpay back office. If the object is not present, the back office settings are used. You can also specify only some of the parameters: if, for example, only the server-to-server notification URL or only one of the redirect URLs is set, the system overrides only the values provided and keeps using the other URLs configured in the Gestpay back office. Below is an example of a request defining all the redirect URLs and the server-to-server notification URL. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID", "responseURLs": { "buyerOK": "https://merchant-url-ok.com", "buyerKO": "https://merchant-url-ko.com", "serverNotificationURL": "https://merchant-url-s2s.com" } } ``` --- ## Payment flow An API Only payment always starts with the `payment/create` call, which initialises the transaction. The next step depends on the payment method: | Method | Calls | Presentation to the buyer | | -------------------------------------- | -------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Cards and wallets** | `payment/create` and `payment/submit` | The merchant collects the details with their own form, or through the wallet SDKs, and sends them to Fabrick with `payment/submit` | | **Alternative payment methods (APMs)** | `payment/create` with `paymentType` and `paymentChannel` | The buyer is redirected to the service through the link returned by `payment/create` (see [Payment method presentation logic](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#payment-method-presentation-logic)) | The following steps describe the card and wallet flow. Checking the outcome, described in [Step 4](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/integration-methods/api-only/#step-4--checking-the-outcome), applies to all payment methods. > **API requests for APMs** > > Each alternative payment method has specific fields and rules for the API request: the request and response examples are described in the *API integration* section of the page of each method (see [Alternative payment methods](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/)). ### Step 1 — Payment initialisation Perform the `payment/create` call on the server side: it requires the API key, which must never be exposed in the client code. **Request** ```http POST /api/v1/payment/create Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "amount": "100", "currency": "EUR", "shopTransactionID": "FBK_OrderID" } ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "paymentToken": "7ebd948a-c9ad-44c9-ac43-02b0beb55a7a", "paymentID": "1541109548247", "userRedirect": null, "qrCode": null } } ``` The response contains: - `paymentToken`, to be used in the header of the `payment/submit` call - `paymentID`, the identifier of the transaction, to be used to check its outcome The `payment/create` call can be extended with the services provided by Fabrick, for example [tokenization](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/token/), [recurring payments](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/recurring-payments/) or [fraud prevention](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/features/fraud-prevention/fabrick-guaranteed-payments/). ### Step 2 — Sending the payment details Unlike the hosted integrations, in which the buyer is redirected to a Fabrick page, with API Only the payment details are sent through the `payment/submit` call, populating the **`PaymentToken`** header with the `paymentToken` received in the previous step. **Card details** Send the card details in the `paymentTypeDetails.creditcard` object. > **Card data security** > > Card data can pass through the merchant's server **only if that server is part of a PCI DSS compliant environment**, with compliance validated through an **AOC** (and, if required by the level, a **ROC**). > > Without PCI DSS compliance, the data must be collected through a **form displayed in the buyer's session** and sent to Fabrick with `payment/submit` **on the client side**: in this way the card data never passes through the merchant's systems. **Request** ```http POST /api/v1/payment/submit Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it PaymentToken: 7ebd948a-c9ad-44c9-ac43-02b0beb55a7a Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "CREDITCARD", "paymentTypeDetails": { "creditcard": { "number": "4012000000003101", "expMonth": "05", "expYear": "27", "CVV": "123" } } } ``` **Tokenized card** If the card has already been tokenized, send the token in the `paymentTypeDetails.creditcard.token` field. The call can be performed on the server side, since no card data is involved. **Request** ```http POST /api/v1/payment/submit Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it PaymentToken: 7ebd948a-c9ad-44c9-ac43-02b0beb55a7a Content-Type: application/json ``` ```json { "shopLogin": "GESPAY12345", "paymentType": "CREDITCARD", "paymentTypeDetails": { "creditcard": { "token": "40ZUU8NXALR33101" } } } ``` > **Apple Pay and Google Pay** > > For wallets, the body of the `payment/submit` call contains the payload returned by the Apple or Google SDKs. Requirements, configuration and payloads are described in the *API integration* sections of the [Apple Pay](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/apple-pay/) and [Google Pay](https://docs.fabrick.com/en/payment-hub-and-orchestra/ecommerce/alternative-payments/google-pay/) pages. ### Step 3 — Handling the response The response to `payment/submit` can present three scenarios: **Authentication required** The `transactionErrorCode` field returns `8006`: you need to redirect the buyer to their bank's authentication page, using the link in `payload.userRedirect.href`. Once authentication is complete, the buyer is redirected to the positive or negative outcome URL. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionErrorCode": "8006", "transactionErrorDescription": "Verify By Visa", "paymentID": "1541109548247", "userRedirect": { "href": "https://sandbox.gestpay.net/pagam/pagam3d.aspx?a=GESPAY12345&b=7ebd948a-c9ad-44c9-ac43-02b0beb55a7a&axerve3D=True&IsLightBox=False" } } } ``` **Immediate outcome** If authentication is not required, the outcome is returned **immediately** in response to the call. **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "submit", "transactionResult": "OK", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction correctly processed", "bankTransactionID": "4858", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "428125", "paymentID": "1541109548247", "currency": "EUR", "country": "SINGAPORE", "company": "VISA", "tdLevel": "", "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": {}, "alertCode": "", "alertDescription": "", "cvvPresent": "Y", "maskedPAN": "47ZUU896G2C40050", "paymentMethod": "", "productType": "Credit", "token": "47ZUU896G2C40050", "tokenExpiryMonth": "05", "tokenExpiryYear": "27", "userRedirect": { "href": "https://merchant-url-ok/ko.com" } } } ``` **Error** The response contains the `error` object with the `error.code` code and the `error.description` description. See the [full list of errors](https://api.paymentorchestra.fabrick.com/#errors). **Response** ```json { "error": { "code": "1119", "description": "Credit card number with wrong length" }, "payload": {} } ``` ### Step 4 — Checking the outcome At the end of the payment, with any method, including APMs, the system sends a **server-to-server (S2S) notification** with the outcome of the transaction. When the buyer returns from an external flow, such as 3DS authentication or payment on an APM, they are also redirected to the positive or negative outcome URL. Example of redirect URL and S2S notification: - `https://merchant-url.com?a=GESPAY12345&Status=OK&paymentID=1541109548247&paymentToken=7ebd948a-c9ad-44c9-ac43-02b0beb55a7a` The redirect URL and the S2S notification contain the **`Status`** parameter, which immediately identifies the status of the payment. The possible values are: - **`OK`**: payment completed with a positive outcome - **`KO`**: payment completed with a negative outcome - **`XX`**: payment on hold, awaiting the final outcome > **Suspended status (XX)** > > The **`XX`** status is used only by some alternative payment methods (APMs) and is returned when the outcome is asynchronous. In this scenario Fabrick redirects the buyer to the positive outcome URL, but the status is **not yet final**: you need to wait for a subsequent S2S notification communicating the final outcome (**OK** or **KO**). > > - If you receive the XX status, do not ship the goods or deliver the service. > - Wait for the S2S notification communicating the final outcome of the payment. To check the outcome or the updated status of the transaction you can use the **`GET payment/detail`** endpoint, passing as a parameter the **`paymentID`** returned by the **`payment/create`** call or obtained from the redirect URL or the S2S notification. The response contains the **`transactionResult`** parameter, which indicates the status of the payment. The possible values are: - **`AUTHENTICATED`**: payment authenticated (OK) - **`APPROVED`**: payment approved (OK) - **`DECLINED`**: payment declined (KO) - **`PENDING`**: payment awaiting confirmation (XX) - **`WAITING`**: payment in progress (XX) - **`UNSUBMITTED`**: the payment has not started yet (XX) Example of a call to check the status of the transaction through the paymentID. **Request** ```http GET /api/v1/payment/detail/{paymentID} Host (sandbox): sandbox.gestpay.net Host (production): ecomms2s.sella.it Authorization: apikey **************** Content-Type: application/json ``` **Response** ```json { "error": { "code": "0", "description": "request correctly processed" }, "payload": { "transactionType": "detail", "transactionResult": "APPROVED", "transactionState": "AUT", "transactionErrorCode": "0", "transactionErrorDescription": "Transaction correctly processed", "bankTransactionID": "1825", "shopTransactionID": "FBK_OrderID", "shopTransactionID_2": "", "authorizationCode": "794183", "paymentID": "1541109548247", "currency": "EUR", "country": "ITALIA", "company": "VISA", "tdLevel": "FULL", "threeDS": { "authenticationResult": { "authenticationLevel": "2C", "authenticationStatus": "Y", "authStatusReason": "", "challengeResultTransStatus": "", "XID": "1dd3cf75-92a7-4487-abb5-b1f3cdd68f3b", "AV": "MTIzNDU2Nzu5MDA5ODc2NTQzMjE=", "ECI": "05", "AVAlgorithm": "", "threeDsVersion": "2.2.0" }, "transDetails": { "authData": "", "authMethod": "02", "authTimeStamp": "202505131259", "acsID": "f688e45c-ff27-4ba6-a631-4b68df2dbf99" } }, "events": [ { "event": { "eventtype": "AUT", "eventamount": "0.00", "eventdate": "13/05/25 13:01:52", "eventARN": "", "eventID": "", "eventReferred": "" } } ], "buyer": { "name": "", "email": "" }, "risk": { "riskResponseCode": "", "riskResponseDescription": "" }, "customInfo": null, "alertCode": "", "alertDescription": "", "cvvPresent": "TRUE", "dcc": null, "maskedPAN": "", "paymentMethod": "VISA", "productType": "Credit", "token": "40G5LMXUQQ613101", "tokenExpiryMonth": "05", "tokenExpiryYear": "27", "tokenDetails": { "TokenValue": "40G5LMXUQQ613101", "TokenExpiryMonth": "05", "TokenExpiryYear": "27", "TokenProvider": "AXERVE", "CardDetails": { "CardSuffix": "3101", "CardExpiryMonth": "05", "CardExpiryYear": "27", "CardHolderName": null }, "CardAssets": { "CardArt": { "Type": null, "MediaContents": null, "Height": null, "Width": null }, "BrandLogo": { "Type": null, "MediaContents": null, "Height": null, "Width": null } } }, "fraudPrevention": { "check": "FALSE", "state": "", "description": "", "order": "" }, "automaticOperation": { "type": "CAN", "date": "07/06/25 00:00:00", "amount": "0.00" } } } ```