Menu

Server to Server – Cards

Card payments are available for Visa and Mastercard cards, using a token or full card details.

Card payments flow may differ slightly depending on the exact use case:

  • One time purchase (learn more…)
  • Payment authorisation and subsequent charge only upon order delivery (total or partial)
  • Payment authorisation with 3DS authentication (frictionless or challenged) (learn more…)
  • Payment based on card token (learn more…)
  • Recurring, merchant initiated payment (learn more…)

How it works

Flow – Authorisation and Capture

Use the authorisation flow when the customer is only charged (totally or partially) when goods or services are provided afterwards.

This flow resembles the “one time purchase” flow, but an additional step is required to actually charge the customer for the goods or services – the Capture (please refer to the Backoffice operations for further details).

The Capture can be for the total amount of the purchase, or for part of it, in which case, multiple Captures accepted up to the authorisation’s full amount.

card aut

Starting by creating the checkout

First, perform a server-to-server POST request, the same as Form Integration, to prepare the checkout with the required data, where you should include the payment type, amount, currency and payment methods allowed.

If already sure that only Card payment is required, then only include “CARD“ in the transaction.paymentMethod list.

For this flow make sure the transaction.paymentType holds the value “AUTH”.

The JSON of your POST body, can be composed of various Complex Types:

The response to a successful request is a JSON with a transactionID, which is required in the second step to create a transaction.

With the transactionID, will be present as well a transactionSignature that will be used on the following step

Expected Response

A success response comprises of an HTTP-200 status, a transactionID and a transactionSignature

Any other HTTP status signals an unsuccessful request. The following statuses may occur:

  • HTTP-400 (Bad Request): The JSON payload is not matching the API definition or some mandatory HTTP headers are missing. Please check in API Market for the correct syntax.
  • HTTP-401 (Unauthorized): The Authorisation: Bearer token is invalid/expired or not associated with the Terminal used. Please check in SIBS Backoffice under the Credentials if the token is valid, and create a new one if needed.
  • HTTP-403 (Forbidden): The ClientID set on the X-IBM-Client-Id HTTP header is not valid or does not possess a valid subscription to the API. Please check in SIBS Backoffice under the SPG APP 2.0 if the ClientID is correct. If the problem persists contact SIBS Gateway support for a ClientID reset.
  • HTTP-405 (Method Not Allowed): The HTTP Method used is not matching any of the API definitions available. Please check in API Market for the correct HTTP Method.
  • HTTP-429 (Too Many Requests): The API calls rate limit has been exceeded. Please check in API Market for information on the rate limits that apply to the API.
  • HTTP-500 (Internal Server Error): The API call has failed… and its most likely on our side. You should retry the operation, and if the problem persists contact SIBS Gateway support for assistance.
  • HTTP-503 (Service Unavailable): The API call is not currently available. Usually we are always on, but short availability issues may occur during scheduled maintenance.
 

Next the transaction has to be generated:

Note that the following request needs an Authorisation Header with the transactionSignature returned from checkout operation.

In this requests, the Bearer Token is replaced by the checkout response transactionSignature.

Example:

Authorisation: Digest {transactionSignature}

Expected Response

A successful technical response comprises of an HTTP-200 status and a returnStatus.statusCode=”000″.

The paymentStatus in the response informs on whether the transaction itself was accepted, declined, still pending a final result, or requiring additional action to be taken.

  • Success: The authorisation has been processed successfully and the customer funds have been validated.
  • Declined: The authorisation has been declined.
  • Pending: The final result of the authorisation is not yet known. You will need to inquiry on the status of this transaction until it reaches a final state, or you decide to cancel it.
  • Partial: The authorisation is partially accepted, but requires additional actions to the completed (e.g. 3D-Secure authentication). The actionResponse element is provided for instructions on how to proceed.

 

Capture

A Capture is used to request clearing for previously authorized funds.

A Capture request is performed using a previous preauthorisation (AUTH) payment by referencing its transactionID and sending a POST request over HTTPS to the /payments/{transactionID}/capture endpoint.

Captures can happen in different ways:

  • Full, capture the full amount authorized and finish the purchase
  • Partial, split the capture over one or several capture requests, up to the total amount authorized

POST https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/capture

Afterwards you can perform a Get Status

Once the payment has been processed, you can check the status of your transaction making a GET request.

The Authorisation HTTP header is set to the Bearer token as it was used in the initial Checkout.

Request URL: 
     https://stargate-cer.qly.site1.sibs.pt/api/v1/payments/{transactionID}/status
 
Request Headers: 
     Autorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6I (...)
     X-IBM-Client-Id: b4480347-9fc8-4790-b359-100a99c60ea3
     Content-Type: application/json

What’s Next

Have a look at the other Card payment features you can use.