Gateway API Integration Guideline

1. Prerequisites

Before you begin integration, ensure the following:

• You have an active merchant account with bbpay.
• You have access to the Shop API Key to call API endpoints and the Shop Signing Key for webhook verification. The keys for the sandbox and production environments are different.
• All requests must:
  • Use HTTPS (base URL: https://engine.bbpay.one for production, https://engine-sandbox.bbpay.one for sandbox environment)
  • Be made using HTTP POST, GET, or PATCH methods as specified
  • Include the Shop API Key in the Authorization header as a Bearer token
  • Use JSON as the request body format for POST and PATCH methods

2. Main API Endpoints

3. Integration Options

🔁 Standard Flow

1. Create Payment via POST /api/v1/payments
2. Receive response with redirectUrl
3. Redirect the customer to redirectUrl for completing the payment

When using the basic_card payment method, the same process applies to both StS integration mode (card data is collected on the merchant side) and hosted page integration mode (card data is collected on the payment gateway checkout page). There is also no difference in the process for 3DS and non-3DS payments.

🔄 Option to Skip Redirection to Checkout Page

Purpose

The option to skip the checkout page provided by the System may become useful in cases when the data required to effect the payment is collected exclusively by the Merchant and does not require a redirect to 3rd-party resources.

Some cases when this can be used:

1. Bank transfer when the Merchant only needs to show payment instructions to the Customer.
2. The Service Provider needs to make a PUSH notification to the Customer to effect the payment.
3. The Merchant collects all required payment info via GooglePay/ApplePay.

Contact System support before integration.

Flow Overview

The flow is as follows:

1. The Merchant collects the payment data from the Customer (for example, by means of its own checkout page).
2. The Merchant creates a payment via POST /api/v1/payments providing the collected data.
3. The System responds and the Merchant extracts the id from the response, ignoring redirectUrl.
4. The Merchant makes a PATCH /api/v1/payments/{id} request with the customer’s IP (as detailed in the Gateway API section).
   • Upon receiving the PATCH request, the System makes a respective request to the Payment Provider. Once the Payment Provider responds, the System responds to the Merchant's PATCH request with the data obtained from the Payment Provider.
   • The externalRefs object in the PATCH response may be used to pass further payment instructions to the Customer from the Payment Provider.
   • NOTE: The PATCH request is synchronous which means that if the Payment Provider fails to respond, the PATCH request will also fail.

ApplePay / GooglePay Notes

In this scenario, ApplePay tokens collected by the Merchant may be used at all times.

As for GooglePay tokens, only tokens of type 'Cryptogram 3DS' may be used in this workflow (as they do not require a redirect to an external authorization resource). Tokens of type 'PAN Only' usually require a redirect (either to complete a 3DS authorization or to collect CVV). In that case, the Merchant should use the standard flow with the System checkout page.

Basic Card Notes

For Basic Card payment methods, this scenario is available only with non-3DS channels.

4. Getting Final Payment Status

Caution: for some payment methods the final transaction amount may be different from the initial requested amount.

4.1. Webhook Handling

• Webhooks notify you when a payment reaches a final state: COMPLETED, DECLINED, CANCELLED, AUTHORIZED
• Configure your webhook URL either:
• In shop settings, or
• Inline using the webhookUrl parameter in the POST /api/v1/payments request (overrides settings).

Webhook Verification

• Set a Signing Key in the shop settings.
• Webhook requests include a Signature header with an HMAC-SHA256 hash of the JSON body using the Signing Key.

Example Payload (DEPOSIT - CANCELLED)

{
  "id": "9e9003d7f3324fc6828481c665d8bab5",
  "paymentType": "DEPOSIT",
  "state": "CANCELLED",
  "paymentMethod": "BANKTRANSFER",
  "amount": 2000,
  "currency": "CLP",
  "errorCode": "1.04",
  "errorMessage": "Cancelled by Timeout"
}

4.2. Checking State by Payment ID

• You can request payment status by sending the request GET /api/v1/payments/{id}

Example Response (DEPOSIT - DECLINED)

{
  "timestamp": "2020-10-07T13:36:32.595+00:00",
  "status": 200,
  "result": {
    "id": "91d27876e87f4b22b3ecd53924bf973d",
    "referenceId": "payment-123",
    "created": "2030-12-25T10:11:12",
    "paymentType": "DEPOSIT",
    "state": "DECLINED",
    "description": "Deposit via TEST shop",
    "paymentMethod": "BASIC_CARD",
    "paymentMethodDetails": {
      "customerAccountNumber": "400000***0002",
      "cardToken": "3529d42227424875af8722cbf54d7073",
      "cardholderName": "John Doe",
      "cardExpiryMonth": "01",
      "cardExpiryYear": "2030",
      "cardBrand": "VISA",
      "cardIssuingCountryCode": "CY"
    },
    "amount": 11.12,
    "currency": "EUR",
    "customerAmount": 15,
    "customerCurrency": "USD",
    "errorCode": "4.01",
    "errorMessage": "Insufficient Funds",
    "externalResultCode": "03",
    "customer": {
      "referenceId": "customer_123",
      "citizenshipCountryCode": "AU",
      "firstName": "John",
      "lastName": "Smith",
      "dateOfBirth": "2001-12-03",
      "email": "[email protected]",
      "phone": "357 123123123",
      "locale": "ru"
    },
    "billingAddress": {
      "addressLine1": "7, Sunny street",
      "addressLine2": "Office 3",
      "city": "Limassol",
      "countryCode": "CY",
      "postalCode": "4141",
      "state": "CA"
    }
  }
}