Prerequisites (once per merchant/environment)

You need the following credentials and configuration elements before calling the SIBS SPG APIs:

• AuthToken : (used as Authorization: Bearer <AuthToken> for REST calls),
• TerminalId : the terminal ID assigned to the merchant, by the SIBS OnBoarding team
• X-IBM-Client-Id : merchant application identifier assigned by the SIBS OnBoarding team

Choose the appropriate environment URLs. The API base URL (<ROOT_URL>) and hosted widget URL (<WIDGET_URL>) must correspond to the same environment.

For environment-specific URL values, refer to A.3 – API Requests.

API Request Flow

The following diagram summarizes the complete Credit Card Form Integration flow before the detailed implementation steps.

1) Create the Checkout Session (server-to-server)

Goal: Create the checkout session in SIBS SPG and obtain the identifiers required to render the hosted Credit Card payment form.

Implementation steps

1.1 POST Checkout Payment to:

curl -v -X POST '<ROOT_URL>/payments' \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json" \
--data '
{
    "merchant": {
      "terminalId": "<TerminalId>",
      "channel": "web",
      "merchantTransactionId": "teste 123"
    },
    "transaction": {
      "transactionTimestamp": "2028-12-31T00:00:00.000Z",
      "description": "Teste",
      "moto": false,
      "paymentType": "PURS",
      "amount": {
        "value": "<amount>",
        "currency": "EUR"
      },
      "paymentMethod": [
        "CARD"
      ]
    },
    "customer": {
      "customerInfo": {
        "customerName": "Onboarding",
        "customerEmail": "Onboarding@teste.com",
        "shippingAddress": {
          "street1": "Rua 123",
          "street2": "Porta 456",
          "city": "Lisboa",
          "postcode": "1200-999",
          "country": "PT"
        },
        "billingAddress": {
          "street1": "First street",
          "street2": "Menef Square",
          "city": "Lisbon",
          "postcode": "1700-123",
          "country": "PT"
        }
      }
    }
  }'

Headers

• Authorization: Bearer <AuthToken>
• X-IBM-Client-Id: <ClientId>
• Content-Type: application/json
• Accept: application/json

Implementation steps

• Create a new payment session.
• Define the payment type (PURS for one-off purchase).
• Restrict the payment method to "CARD".
• Provide customer information as required by the merchant configuration defined during onboarding.
• Send the total amount and currency.

This call registers the payment and prepares the transaction for the hosted form.

1.2. Store from the successful response:

The SPG transactionID should be treated as the authoritative identifier for transaction monitoring, webhook correlation, reconciliation, refund operations, and Status Inquiry requests throughout the transaction lifecycle.

From the Checkout response, you must store:

• transactionID : (you’ll inject it in the widget script URL)
• transactionSignature : (you’ll inject it into the HTML form attribute)
• formContext : (you’ll inject it into the HTML form attribute)
• paymentMethodList : (SIBS SPG may also return available methods)

These values are required to:

• Load the SIBS SPG widget
• Render the payment form
• Perform server-side status validation

Notes

• merchantTransactionId is your internal order identifier (max 35 characters).
• paymentType must be "PURS" for one-off purchase
• The customer.customerInfo block is required for Credit Card transactions according to the merchant configuration defined during onboarding.
• The checkout session expires after 10 minutes. If the session expires, a new checkout must be created.

2) Create the payment form link (Widget) + customization (front-end)

Goal: Render the SIBS SPG payment form, collect cardholder payment details, and allow the customer to complete the payment authorization flow.

2.1 Include the SIBS SPG widget script (using transactionID)

Add the script tag to your checkout page:

<script src="<WIDGET_URL>/assets/js/widget.js?id={transactionID}"></script>

This is the standard Form Integration approach and the script URL includes the transactionID.

2.2 Add the <form> element and inject formContext + transactionSignature +config/style

You must have a form with class paymentSPG and the SIBS SPG attributes:

<form class="paymentSPG"
      spg-context="{formContext}"
      spg-signature="{transactionSignature}"
      spg-config="{formConfig}"
      spg-style="{formStyle}">
</form>

SIBS SPG explicitly defines:

• spg-context : the formContext you received from Checkout
• spg-signature : the transactionSignature you received from Checkout
• spg-config : merchant configuration (JSON string),
• spg-style : optional styling configuration (JSON string).

2.3 formConfig – minimal config for Credit Card one-time

At minimum, your config should:

• Restrict the form to Credit Card using paymentMethodList
• Set redirectUrl (where the customer returns after the form finishes)
• The amount is defined in the Checkout request and does not need to be redefined in formConfig.
• Set language to match your checkout language.

Example (conceptual):

const formConfig = JSON.stringify({
  paymentMethodList: ["CARD"],
  redirectUrl: "https://merchant.example.com/payment-return",
  language: "en"
});

Supported values for paymentMethodList include MBWAY, REFERENCE, CARD (display depends on merchant permissions).

2.4 formStyle – optional UI customization

If you want to align the SIBS SPG form with your brand, SIBS SPG supports a style object with parameters like layout/theme/colors/font.
Example (conceptual):

const formStyle = JSON.stringify({
  layout: "default",
  theme: "light",
  color: { 
      primary: "#0033A1" 
  }
});

Optional: react to “Pay” click events in real time

SIBS SPG supports event monitoring via window.postMessage from the iframe so you can show a spinner / tracking / UX actions when the user clicks “Pay”.

What Happens After Form Submission?

1. The customer enters card details in the hosted form.
2. The transaction is sent to the acquiring network.
3. Strong Customer Authentication (3D Secure) may be automatically triggered by the issuer.
4. The issuing bank approves or declines the transaction.
5. The customer is redirected to the configured redirectUrl.
6. The final payment status must be confirmed server-to-server (Step 3).

Credit Card Behaviour

• Credit Card is a real-time payment method.
• Authorization response is typically immediate in non-3DS scenarios.
• 3D Secure authentication may introduce a short processing period.
• The transaction may temporarily remain in Pending while authentication or transaction processing is being completed.
• The payment must only be considered completed when paymentStatus = Success.

Notes

• The hosted form is PCI DSS compliant and securely handled by SIBS SPG.
• All cardholder data (PAN, secureCode, validationDate, cardholderName) is collected exclusively inside the SIBS SPG environment.
• Card data never touches the merchant server, significantly reducing PCI DSS scope.
• If the checkout session expires (10 minutes), the hosted form will no longer load correctly, and a new checkout session must be created.
• Even after redirection, the final transaction result must always be validated via the status endpoint.

3) Validate the Final Transaction Status (Back-End)

Goal: Confirm the final payment outcome after the customer completes the Credit Card payment flow.

Even though Credit Card is a real-time payment method, the final result must always be validated server-to-server.

3.1 When to check status

You should verify the transaction status:

• After the customer is redirected to the redirectUrl
• After receiving a webhook notification, if configured

Unlike Multibanco Reference, Credit Card payments do not remain pending for extended periods.

However:

• During 3D Secure authentication, the transaction may temporarily remain in Pending while the authentication result is being processed by SPG.

The transaction must only be considered finalized after confirming the status via API.

Important: The redirectUrl does NOT guarantee that the payment was successful. Always confirm the final payment outcome server-side.

3.2 Status endpoints you can use

The following Status Inquiry options are commonly used:

• GET <ROOT_URL>/payments/{transactionID}/status
• GET <ROOT_URL>/payments/status?merchantTransactionId=... (query by your merchant transaction id)

curl -v -X GET "<ROOT_URL>/payments/{transactionID}/status" \
--header "X-IBM-Client-Id: dd43****" \
--header "Authorization: Bearer 0276****" \
--header "Accept: application/json" \
--header "Content-Type: application/json"

For example, s2iCzUbsAAs5CSjzSFVE represents a transactionID returned by the Checkout request.

3.3 Required headers (status call)

• Authorization: Bearer <AuthToken>
• X-IBM-Client-Id: <ClientId>
• Content-Type: application/json
• Accept: application/json

3.4 What statuses to expect (high level)

The response includes paymentStatus, typically with values such as:

• Success
• Declined
• Error
• Pending
• Timeout

Credit Card behaviour

• Success : Authorization approved and funds captured (for paymentType = PURS)
• Declined : Transaction refused by issuer
• Error : Technical or processing error
• Pending : Temporary state during authentication or processing (e.g., 3D Secure challenge flow)

The transaction must only be considered completed when paymentStatus = Success.

3.5 Recommended validation strategy

For Credit Card Form Integration:

• After redirection, immediately call the /status endpoint.
• Do not rely solely on front-end redirection parameters.
• If Pending, retry status after a short delay (few seconds).
• Stop when a final state is reached (Success, Declined, Error, Timeout).

Polling for Credit Card should be short-lived and limited to the authentication window.

Webhook notifications should be treated as the preferred mechanism for transaction lifecycle monitoring and operational reconciliation.

The Sandbox Payment Simulator may also be used to validate Credit Card Form Integration flows, hosted payment form behaviour, customer authentication scenarios, transaction lifecycle progression, and operational request/response payloads in the sandbox environment.

Example sandbox simulator entry point

For webhook delivery and processing guidance, refer to E.1 – Webhooks (Notifications).

For transaction lifecycle monitoring and Status Inquiry operations, refer to E.2 – Status Inquiry / Get Status.

Important Notes

• Credit Card is a real-time payment method, except when Strong Customer Authentication (3D Secure) introduces an authentication step.
• There is no extended waiting period (unlike Multibanco Reference).
• The final payment confirmation must always be validated server-to-server.