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:

https://test.paywith.billpocket.com/api/v1/

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:

https://paywith.billpocket.com/api/v1/

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:

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

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] If you don't send this field we are going to add the plans configured to your account, if you don't want to offer any plan just send an empty array.	Array[]

Example of usage

Response Format (HTTP 201: OK)

Field	Description	Type

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

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 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

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

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

Billpocket Public Docs

Pasarela de pagos: 3D Secure Online Transaction API

Abstract

Billpocket and Your App

3D Secure Online Transaction Overview

Infrastructure Requirements

Paywith Webhook and Redirect Parameters

API Key

Webhook for 3D Secure Online Payment Response

Webhook for Redirect

Update webhooks

3D Secure Online Card Transactions

Creation of a shopping cart (Checkout – Creation)

Request Format

Example of usage

Response Format (HTTP 201: OK)

Example of successful response message (HTTP 200)

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)

Example of usage

Response Format

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

Flowchart