Pasarela de pagos: 3D Secure Online Transaction API
Abstract
This document describes Billpocket’s API for 3D Secure online transactions processing, that allows third-party entities to securely process card-not-present transactions by providing the enough information for MasterCard SecureCode and Verified by Visa validations before proceeding with the online transaction.
The following pages will detail the format, parameters and semantics of the requests handled by Billpocket System, as well as the response parameters and values.
Billpocket and Your App
Billpocket allows any app and webApp to process 3D Secure online transactions. For this, you will create “checkouts”, which are self-contained authorization requests ready to be completed by any user.
The checkout creation API will return UUIDs used to construct checkout URLs. Given this URL, your web code must perform an HTTP redirection so the user can complete the authorization.
Three points must be properly managed to achieve a correct integration development:
1. All POST request must be sent in json format.
2. All GET request will feature the parameters in the URL query section.
3. All response payloads are in json format, except when noted.
Our Demo/Test API’s Base URL is:
This endpoint does not process the transaction on a production-environment but provides valid responses to the requests. Once your development has been validated and certificated, you will receive your production-environment API Key.
Our Production API’s Base URL is:
3D Secure Online Transaction Overview
Our API for integrating of the 3D Secure Online Transaction process, provides one method to create and submit a shopping cart to Billpocket System, and allows the usage of an URL to perform the payment transaction.
The steps to perform the 3D Secure payment transaction are:
Creation of a shopping cart in Billpocket System (Checkout – Create Method).
Performing of the 3D Secure Online Transaction (Request by URL).
Receiving of the transaction response for your application internal handling
Also, our API offers some other methods to:
Deactivating a shopping cart previously submitted.
Retrieving information from a shopping cart.
You should always choose a Web Browser like Chrome, Safari or Firefox to ensure that the transaction results are sent to the correct address for your application to process them.
Infrastructure Requirements
Paywith Webhook and Redirect Parameters
The 3D Secure online payment process requires two URLs to be created and configured. They both should have a valid SSL/TLS certificate from a valida CA (even for testing environment).
One of the webhooks will be used for receiving the 3D Secure response in JSON format as a POST message, and the other one for the redirect of the response. Both request will have all the parameters needed to identify and validate the authorization notification.
API Key
To create and configure de API Key, it’s needed to create the webhooks first. Once they are created, the Billpocket crew will create and provide the API Key to client. We need a public PGP key so we can send your API Securely to you, you can use any tool for this, we recommend using Mailvelope
Notes:
Once the Billpocket team confirm the api key was generated, you can get your api key on the Billpocket Dashboard
Sandbox: Billpocket Dashboard - Sandbox
Production: Billpocket Dashboard - Production
Api key format: XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX
Webhook for 3D Secure Online Payment Response
The following is an example of a 3D Secure online payment response to be sent to the corresponding webhook:
{
checkout: "cec4b9bf-5a39-4bd7-bc8b-826ebc18208d",//Checkout ID
externalId: "Internal_0005",// Unique ID specified when this checkout was created (String)
total: "12",//Total amount paid for this checkout
authorization: "BP7610", //Transaction authorization number
ticketUrl: "fcbdf2bdb9c2d9636594702ac076f16775072d00", // Hash to retrieve the transaction ticket at https://www.billpocket.com/api/v1/ticket/ticketURL
opId: "39679", // Billpocket's Transaction ID
maskedPAN: "415231******8397", //Masked card number used to complete checkout
message: "APROBADA", // Approval message
token: "947d589a40dece13c28f2b63c41ae451", // Unique token for this transaction
cardCountry: "MX", // Card Countrty
cardBrand: "VISA", // Card Brand
cardIssuer: "BANCOMER", // Card Issuer
cardClass: "DEBIT", // Card Class
signature: "V/5QqjPUBacXnm0Us6hHYSPD8bpSqLdbsZQXDAqUExoK+NwTIoyjvVIpwGNi7Bdbq5Yw8PyDToVibva82o13k4T+7DCbZIrv7kylfdY/RRYGq3O4tH9ptjl1aIz2FWDCWMlcHjYRyEHhelJSw0W38f3FB7e8i5pdmRHUdJRaiapostcPgnxly2sz9GX1iw9eFwiGG1jqCieIvvXDPiV2V6NQYqG8YaHwSem+9w3Ki+AAx5k1tayV5k6sTHbjpc5KChdTKQyfEXpZLQY5Pr3+H2+uXug8Dj0uDb21Dh68VKxkF4Wy72Vf3Jzx3ozExDvlRgsmzkMTiXF1zggeOQISLKd/sGMcm0oQpflW+ROTqp6tWKFWHk1afyaJPGIXKUZaRyoG28tehZ5AHxLCCOzNQc1FJbtKUx0WG7egebA6563NOSMPT2TmGGvTjSlt8Fso9YXCn/5Jfv/VNAzYuxdccD4bSu8Xc3YZOHDfmSuav/xUicQ9A6mDKsXz17bbLVVB0UrR7wbd4qcjUVGx6f8RlFc7EMhGPGmoO/iiitQYy6VRAKlb5gArvdvWqWnEdy+4wdMzEFsvsUg/by9mhuu8vtJyUQIan5VdBokJougKLIQfKdcFKBtzkRvm1QGkfCPB5vHdmzQilBa5jzzaj44Qb7rC0G6/bavZeDSqho4Ptis="// Signature for this payload.
}
The signature parameter is calculated using the response data and transforming it into its canonic form:
checkout|externalId|total|opId|authorization|token
For the given example, canonic form is as follows:
cec4b9bf-5a39-4bd7-bc8b-826ebc18208d|Internal_0005|12|39679|BP7610|947d589a40dece13c28f2b63c41ae451
We sign the response by hashing the canonic form with SHA-256 and encrypting the resulting bytes with our private key.
RSA_ENCRYPT(SHA256( canonicForm ), billpocket_privkey.key)
To verify the payload, you must recalculate the canonic form and apply SHA-256 to the result. The resulting value must be compared with the result of decrypting the signature parameter with our public key. This public key is delivered as part of the integration process. There are different keys for Dev and Production environments.
Unless otherwise indicated, the keys used to validate our signatures are available in .pem and .der forms for download here:
Webhook for Redirect
The following is an example of a 3D Secure online payment response to be sent to the webhook for response:
https://exampledomain.com?externalId=GMS2022&total=100.00
&authorization=BP1756
&ticketUrl=950fb2000cc2598a589fe001e3372ffa6f3ee2f0
&opId=54594
&maskedPAN=411111%2a%2a%2a%2a%2a%2a1111
&message=APROBADA
&token=bc781ece586fda245529a96b57c6df79
&signature=vfB3pUymotiFNqRnKy0KqAHqdzq%2BLLWYA3ONgy7yjy8ac9qbMGnuopw2iqxDJAVs88GlP6B44hVqdXX2KWcFV36KxTmrDduDQDgXGkZCf%2FmdqAKFk2KgcMV7H5Zum%2FKjvdEdeGegsUeFG%2Fdm0jzFDdbQ6mQMp2YeB5vt8ThlUJ9aGNoQ2z7up%2B7ti5OWXW2pg21zarWPAf9qTQrpURjdZLegvBjjBJI9Y1d9FWl8HktKjNb1ro3FtLMp6koJgvyJgKwz0NpVrZNSyIxfiGYLz0iaadEAp43K5hlPchSu%2BHd0LZVvZcxrAJcD3%2BHq4NgeJbUTB6DJ6y%2FDjqiKkn3g7Q%3D%3D
&checkout=44d74991-c703-4059-ac8c-0792e3b55ba9
&cardCountry=MX
&cardBrand=VISA
&cardIssuer=BANCOMER
&cardClass=DEBIT
Update webhooks
If you need to change the Webhook redirect or Webhook for 3ds response payment you can do this using your Billpocket dashboard, using the appropriate url:
Sandbox: Billpocket Dashboard - Sandbox
Production: Billpocket Dashboard - Production
3D Secure Online Card Transactions
Creation of a shopping cart (Checkout – Creation)
This method submits a valid shopping cart to Billpocket’s system, before proceeding with checkout.
Request Format
Method: POST
Content-type: application/json
URL: /checkout
Field | Description | Type |
---|---|---|
apiKey | API-Key provided on when you enrolled with us to use this API | String |
externalId | Internal identifier of the transaction in your systems, for tracking purposes. | String |
items | Optional details displayed to the cardholder when completing the transaction. | Array[] |
total | Amount due (min 10.00 MXN). | Number |
description | Some description | String |
rates | Interest free credit for up to 24 months. Example: [3, 6, 9, 12, 18, 24] | Array[] |
Example of usage
Response Format (HTTP 201: OK)
Field | Description | Type |
---|---|---|
items | Echoed from original request. | Array[] |
checkoutId | Checkout unique identifier, you'll use this when redirecting the user to complete the payment. | UUID |
externalId | Echoed from original request for e-commerce internal tracking. | String |
total | Echoed from original request. | Number |
description | Echoed from original request. | String |
rates | Echoed from original request. | Array[] |
createdAt | Creation time. | Date |
updatedAt | Last updated date. | Date |
Example of successful response message (HTTP 200)
Once the response is received, to proceed with the 3D Secure Online Transaction, the following URL must be generated and performed:
https://test.paywith.billpocket.com/checkout/{checkoutId}
Example of checkout not found (Request Error HTTP 404)
HTTP/1.1 404 OK
Example of bad information body (Request Error HTTP 403)
HTTP/1.1 403 { message: message with error }
Example of error found (Request Error HTTP 500)
HTTP/1.1 500 Internal Error server
Retrieving information of a shopping cart (Checkout – Reading)
This method retrieves the information of a shopping cart previously submitted to Billpocket.
Field | Description | Type |
---|---|---|
checkoutId | Checkout UUID as received from the Create Checkout Endpoint. | UUID |
apiKey | API-Key provided on when you enrolled with us to use this API | String |
Example of usage
Response Format
|
|
|
---|---|---|
checkout | Object with checkout information. | Object |
items | Details displayed to the cardholder when completing the transaction. | Array[] |
externalId | Internal identifier of the transaction in your systems, for tracking purposes. | String |
total | Amount due | Number |
description | Description | String |
createdAt | Creation Date | Date |
updatedAt | Last Update Date | Date |
transaction | Authorization data if available (after successful payment) | Object |
status | Transaction Result. (1:Success, 0:Error). | Number |
message | Human-readable message in case of error | String |
opId | Unique transaction identifier. | String |
txnISOCode | Transaction's result ISO Code. | String |
authNumber | Transaction's authorization number. | String |
ticketUrl | Transaction's unique identifier in the ticket system. | String |
maskedPAN | Masked representation (555555******0001) of the PAN used for this transaction | String |
token | token transaction | String |
signature | signature transaction | String |
Example of successful response message (HTTP 200)
Example of successful response message (HTTP 200)
Example of checkout not found (Request Error HTTP 404)
Example of error found (Request Error HTTP 500)
Test cards and Cases
There are two main process flows for 3DS - frictionless and challenge. Frictionless occurs when no cardholder interaction is required during the authentication process. Challenge flow involves a redirection of the cardholder browser to the issuer bank ACS server to complete one or more ‘challenges’ before the authentication.
Authorizations will approve for the following test cases:
Card Number | Expiry Date | CVV | 3DS Version | Notes |
---|---|---|---|---|
4012000000020071 | Any Future Date | Any | 2.1.0 | Frictionless |
4012000000020089 | Any Future Date | Any | 2.1.0 | Frictionless |
5100270000000023 | Any Future Date | Any | 2.1.0 | Frictionless |
5100270000000072 | Any Future Date | Any | 2.1.0 | Frictionless |
4012000000020006 | Any Future Date | Any | 2.1.0 | Challenge |
5100270000000031 | Any Future Date | Any | 2.1.0 | Challenge |
4012010000020070 | Any Future Date | Any | 2.1.0 | Frictionless |
4012010000020088 | Any Future Date | Any | 2.1.0 | Frictionless |
5100271000000120 | Any Future Date | Any | 2.1.0 | Frictionless |
4012010000020005 | Any Future Date | Any | 2.1.0 | Challenge |
341111000000011 | Any Future Date | Any(4 digits) | 2.1.0 | Frictionless |
341112000008012 | Any Future Date | Any(4 digits) | 2.1.0 |
|
Note: credentials just for demo purposes: 3ds2 & 3ds2
Authorizations will decline or not be available for the following test cases:
Card Number | Expiry Date | CVV | 3DS Version | Notes |
---|---|---|---|---|
4012000000020121 | Any Future Date | Any | 2.1.0 | Frictionless, Payment Completion not permitted |
5100270000000098 | Any Future Date | Any | 2.1.0 | Frictionless, Payment Completion not permitted |
5100270000000056 | Any Future Date | Any | 2.1.0 | Challenge, Payment Completion not permitted |
5555666666662222 | Any Future Date | Any | 2.1.0 | Frictionless, Payment Completion not permitted |
341111000000029 | Any Future Date | Any(4 digits) | 2.1.0 |
|
Flowchart
© Billpocket, 2018