Direct integration

In this scheme, an online store has its own payment page to collect card data natively through its web site.

First, you should subscribe to the webhooks (see Webhooks for details) described below.

In case of making a one-step Payment you should subscribe to:

• payment.succeeded - occurs when a payment succeeds.

If a two-step Payment takes place (if captureMethod: manual), you should subscribe to:

• payment.amountCapturableUpdated - occurs when funds for two-step Payment are successfully held.
• payment.funded - occurs when funds for two-step Payment are successfully captured.

Below are webhooks general and necessary for both types of payments:

• payment.created - occurs when a payment is created.
• payment.failed - occurs when a payment attempt fails (please note that multiple payment attempts can only be made in the case of redirect integration).
• payment.canceled - occurs when a payment is declined.

1. A customer selects a product in the online store, and then clicks Buy.
2. The online store server receives a purchase request and opens a payment page.
3. The customer enters their card details on the online store payment page.

4. The online store server sends /payments request to the Payment Gateway to create a Payment (see API Reference for details). The request should contain amount parameter (the amount of the payment in minor currency units, e.g. in cents) and currency parameter (three-letter code of the payment currency, according to ISO 4217). Additionally, you should pass either paymentMethod block with card data or storedPaymentMethod.id parameter (the identifier of a Stored Payment Method).

   Request example:

   curl -X POST "https://dev.bpcbt.com/api2/payments" \
   -H "X-Api-Key: 6HUXQFbeomV1zf5i8cgm5W8KfncENVEa5uh8RngB" \
   -H "X-Version: 2023-10-31" \
   -H "Content-Type: application/json" \
   -d '{
   "amount": 70000,
   "captureMethod": "automatic",
   "currency": "EUR",
   "customerDetails": {
       "address": {
       "city": "Test city",
       "country": "CY",
       "line1": "Test address1",
       "line2": "Test address2",
       "postalCode": "Test postal code",
       "state": "Test state"
       },
       "email": "test@example.com",
       "name": "TEST CARDHOLDER",
       "phone": "+449998887766"
   },
     "description": "Some description",
   "metadata": {},
   "paymentMethod": {
       "type": "card",
       "card": {
       "cvc": "123",
       "expiryMonth": 12,
       "expiryYear": 2024,
       "holderName": "TEST CARDHOLDER",
       "number": "4444555511113333"
       }
   },
   "paymentMethodOptions": {
       "card": {
       "threeDSecureMode": "automatic",
       "verify": false
       }
   },
   "returnUrl": "https://mybestmerchantreturnurl.com/"
   }'

5. Payment Gateway creates a Payment.

6. Payment Gateway sends payment.created webhook to the online store.

7. Online store server sends HTTP Code = 200 in response.

8. Payment Gateway sends the response for the /payments request.

   • If the response contains the nextAction block, this means that 3-D Secure is required. Steps 9 and 10 are performed.
   • If the response does not contain the nextAction block, 3-D Secure is not required. In this case, Steps 9 and 10 are omitted, go to Step 11.
   • If the payment was successfull, the response contains status=succeeded.

   Response example:

   {
   "id": "p_HbtjsyTuig5SWYufjsFeTNAX3WisQFUSvbroA1C48Y5XN8Pstcdw",
   "amount": 70000,
   "amountCapturable": 0,
   "amountReceived": 70000,
   "captureMethod": "automatic",
   "created": "2024-03-31T23:40:24Z",
   "currency": "EUR",
   "customerDetails": {
       "address": {
           "city": "Test city",
           "country": "CY",
           "line1": "Test address1",
           "line2": "Test address2",
           "postalCode": "Test postal code",
           "state": "Test state"
       },
       "email": "test@example.com",
       "name": "TEST CARDHOLDER",
       "phone": "+449998887766"
   },
   "description": "Some description",
   "metadata": {},
   "paymentMethod": {
       "card": {
           "expiryMonth": 12,
           "expiryYear": 2024,
           "holderName": "TEST CARDHOLDER",
           "maskedNumber": "444455**3333"
       },
       "type": "card"
   },
   "paymentMethodOptions": {
       "card": {
           "threeDSecureMode": "automatic",
           "verify": false
       }
   },
   "returnUrl": "https://mybestmerchantreturnurl.com/",
   "status": "succeeded"
   }

9. Online store redirects the customer to the URL for 3-D Secure verification.

10. The customer confirms payment.

11. Payment Gateway processes payment.

12. Payment Gateway sends payment.succeeded webhook to the online store.

13. Online store server sends HTTP Code = 200 in response.

14. Online store sends /payments/{id} request to retrieve a Payment.

15. In response, Payment Gateway sends the Payment object with status=succeeded.