boltPay Checkout
(TODO: Split the texts between checkout and api, that was migrate as it is from confluence)
The most secury and fast way to integrate the boltPay payment capabilty in your system. For that is necessary only few data to create the payment in our end and process with the selected/configured PSP.
Leaving the tokenization process to our end you will not drop off a bunch of development hours. Because of that we advise to use the boltPay checkout to do the job and get the things done.
Let's do it
This is simple to request a payment and get the results. For some payment methods, that delay sending us back the response, we dispose of a callback/notification system that will send to your end all payment updates.
You can check more about boltPay callback/notification module here.
Request
| Information | Description |
|---|---|
| Host | Provided by boltPay |
| Method | POST |
| Endpoint | /v1 |
| Body | raw |
| Content-Type | application/json |
Request body example
{
"amount": "000000000100",
"cardHolderEmail": "[email protected]",
"cardNumber": "5454XXXXXXXX5454",
"cardYear": "2020",
"cardMonth": "10",
"phone": "0900000000",
"productName": "{{Your product name}}",
"locale": "{{configured-and-provided-by-boltpay}}",
"scopeId": "{{provided-by-boltpay}}",
"currencyCode": "{{provided-by-boltpay}}",
"customFields1": "{{your-custom-data-to-link-payment}}",
"customFields2": "{{your-custom-data-to-link-payment}}",
"customFields3": "{{your-custom-data-to-link-payment}}",
"paymentAccount": "{{provided-by-boltpay}}",
"recurring": 1,
"paymentMethod": "cc",
"cardHolderName": "TESTE TESTE",
"encryptedCardInfo": "00acUHNy1OPfq+Ri569v9eZaKHVO8Ff2zN8WUi3FyC3QgE6SSvyXIFMlhUNGoD8yIkAtDj7qAMDMtAwZitCHJhv3utGFr1L45lV9w2lAlCCG4sUKvZtwZMe0Tu/QBUDhvkz1CyXXHXu3DRfrjkcrf52J2X91CI1UgCcFsHW/pGLviIo=U2FsdGVkX1/PAC6ULaN //vd0Nl1INMnj7NB8BH3Osr2bZ/nyojBNBjif/+p6AlR4",
"cardType": "MASTERCARD"
}
Some request fields details
| Field | Description |
|---|---|
| currencyCode |
|
| amount | Amount that will be charged formatted with 12 characters where the last 2 chars represent the cents (fraction) Ex: 000000010199 = 101.99 |
| locale | ba*, da, de, en, fi, fr-be, hk*, id, nl, nl-be, no, ph*, sv, vi* |
| instance | Provided by boltPay |
| scopeId | Provided by boltPay |
| paymentAccount | default or one provided by boltPay |
| paymentMethod |
(More details in Supported Payment Methods) |
| cardType** |
|
| recurring | 0 or 1 If 1 the payment gateway returns in the response a recurringId that can be use request others payments (monthly or another period that client whant to do a new charge) without send all user, card or account information again. (See more in Recurring payments) |
| customFields1 | Free field to enter your system's registration identification information. Example: Order number, Customer number, etc. You can filter payments and recurrences through this free field. |
| customFields2 | Free field to enter your system's registration identification information. Example: Order number, Customer number, etc. You can filter payments and recurrences through this free field. |
| customFields3 | Free field to enter your system's registration identification information. Example: Order number, Customer number, etc. You can filter payments and recurrences through this free field. |
| customFields4 | Free field to enter your system's registration identification information. Example: Order number, Customer number, etc. You can filter payments and recurrences through this free field. |
| encryptedCardInfo | For transparent checkout: we provide a script from the partner that integrates the method to encrypt the data in the client side. For payment-gateway checkout form: It’s not necessary send this information, the PGW form will take care of this encryptation. |
Some payments methods, like Credit Card with 3DS, could not work to integrate in Transparent Checkout.
*Locale codes that is setuped directly in the country servers. Not available for all.
**Required if it’s a Credit Card payment request.
Responses
Without 3DS
Payments without 3DS are credit card payments that is not necessary the OTP authentication.
Success
{
"status": true,
"result": {
"success": true,
"status": "CONFIRMED",
"message": "Approved",
"customFields1": "YOUR_SHARED_DATA",
"customFields2": "YOUR_SHARED_DATA",
"customFields3": "YOUR_SHARED_DATA",
"paymentId": "601437c1f801896274a19aec",
"currencyCode": "201",
"amount": "8000.00",
"invoiceNumber": "1611937744892abb9na",
"bank": "BANK",
"paymentMethod": "cc",
"recurringId": "601437c1f801896274a19aec"
}
}
| Field | Description |
|---|---|
| status | In case of success it will be true, or false in case of failure. |
| result.success | A boolean value (true or false) |
| result.status | The payment status. |
| message | Response message from provider (2c2p,paymaya, fortumo etc) |
| result.recurringId | The ID of recurring (if has recurring) |
| paymentId | ID from payment |
| invoiceNumber | Only in 2C2P |
| bank | Bank Name. Only in 2C2P |
| error | Message from provider |
Failed
{
"status": false,
"result": {
"success": false,
"status": "FAILED",
"message": "Invalid Card Number",
"customFields1": "YOUR_SHARED_DATA",
"customFields2": "YOUR_SHARED_DATA",
"customFields3": "YOUR_SHARED_DATA",
"paymentId": "60137beb4e6bc07fcffdeee1",
"currencyCode": "201",
"amount": "8000.00",
"error": "Payment: 2C2P -- Unique Transaction Code: 16118896589379uy715 -- Error code: 99 -- Error Message: The length of 'pan' field does not match.",
"paymentMethod": "cc"
},
"error": {
"statusCode": 502,
"error": "Bad Gateway",
"message": "Payment: 2C2P -- Unique Transaction Code: 16118896589379uy715 -- Error code: 99 -- Error Message: The length of 'pan' field does not match."
}
}
With 3DS
Provider 2C2P
Using 3DS, your application will receive a JSON from PGW, where the "body" key will send an HTML provided by 2C2P. This HTML must be "injected" into your application to redirect the user to the 3DS page or to the chosen payment method page.
{
"status": true,
"body": "<html><head><meta name='viewport' content='width=device-wi...."
}
Provider Paymaya
The integration with Paymaya will return a JSON with the "url" key, where your application should redirect the user to the URL received.
{
"status": true,
"url": "https://payments-web-sandbox.paymaya.com/paymaya/payment?id=b7cc7e84-f015-42cc-a766-c138ca46b3a7"
}
Callbacks from PGW to your APP
Your application needs to have 2 endpoints to receive payment notifications from PGW.
Backend Callback
This endpoint must return an HTTP Status 200, confirming to PGW that your application has received confirmation of payment confirmation / failure.
Frontend Callback
This endpoint must return a JSON with a "url" key. This URL must be a valid link, to which PGW will redirect the user after payment confirmation / failure.
{
"url": "YOUR_APP_URL_TO_REDIRECT"
}
Callbacks Content Body
For the Backend and Frontend callback, PGW will send a JSON with the same data present in the "result" key, shown in the "Response" section, as follows:
Success
{
"success": true,
"status": "CONFIRMED",
"message": "Approved",
"customFields1": "YOUR_SHARED_DATA",
"customFields2": "YOUR_SHARED_DATA",
"customFields3": "YOUR_SHARED_DATA",
"paymentId": "601437c1f801896274a19aec",
"currencyCode": "201",
"amount": "8000.00",
"invoiceNumber": "1611937744892abb9na",
"bank": "BANK",
"paymentMethod": "cc",
"recurringId": "601437c1f801896274a19aec"
}
Failure
{
"success": false,
"status": "FAILED",
"message": "Invalid Card Number",
"customFields1": "YOUR_SHARED_DATA",
"customFields2": "YOUR_SHARED_DATA",
"customFields3": "YOUR_SHARED_DATA",
"paymentId": "60137beb4e6bc07fcffdeee1",
"currencyCode": "201",
"amount": "8000.00",
"error": "Payment: 2C2P -- Unique Transaction Code: 16118896589379uy715 -- Error code: 99 -- Error Message: The length of 'pan' field does not match.",
"paymentMethod": "cc"
}