Skip to main content

API Only

View as Markdown

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:

ScenarioHow it worksDetails
Card form on the merchant's websiteThe merchant collects the card details with their own form and sends them to Fabrick with payment/submitPayment flow
Payment with a tokenized cardThe merchant sends with payment/submit the token of a previously saved card, without asking the buyer for the details againTokenization
Apple Pay and Google Pay in the merchant's checkoutThe merchant integrates the wallet SDKs and sends the returned payload with payment/submitApple Pay · Google Pay
Alternative payment methods (APMs)The merchant initialises the transaction specifying the APM in paymentType and redirects the buyer to the servicePayment method presentation logic
Recurring paymentsThe merchant initialises the series with an authenticated transaction and carries out the subsequent charges with the tokenRecurring payments with cards and wallets

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).
  • 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).

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 and Satispay.

Full list of paymentType values

The possible paymentType values are listed in the 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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/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:

MethodCallsPresentation to the buyer
Cards and walletspayment/create and payment/submitThe 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 paymentChannelThe buyer is redirected to the service through the link returned by payment/create (see Payment method presentation logic)

The following steps describe the card and wallet flow. Checking the outcome, described in Step 4, 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).

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

POST /api/v1/payment/create
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json
{
    "shopLogin": "GESPAY12345",
    "amount": "100",
    "currency": "EUR",
    "shopTransactionID": "FBK_OrderID"
}

Response

{
    "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, recurring payments or fraud prevention.

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.

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

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
{
    "shopLogin": "GESPAY12345",
    "paymentType": "CREDITCARD",
    "paymentTypeDetails": {
        "creditcard": {
            "number": "4012000000003101",
            "expMonth": "05",
            "expYear": "27",
            "CVV": "123"
        }
    }
}
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 and Google Pay pages.

Step 3 — Handling the response​

The response to payment/submit can present three scenarios:

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

{
    "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"
        }
    }
}

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

GET /api/v1/payment/detail/{paymentID}
Host (sandbox): sandbox.gestpay.net
Host (production): ecomms2s.sella.it
Authorization: apikey ****************
Content-Type: application/json

Response

{
    "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"
        }
    }
}