3DS Checkout

Integrating Checkout is the fastest way to accept online card payments. Obtain a hosted payment form URL from the Billpocket infrastructure, share it with your customers, and receive the result via webhook. The form handles 3D Secure challenges automatically — you never touch sensitive card data.

INFO

Service available in Mexico only.

Requirements

A valid account

An API key

Environments

Environment	Base URL
Dev	`https://test.paywith.billpocket.com`
Live	`https://paywith.billpocket.com`

Configure webhook and redirect URLs

Before going live, configure two URLs from the dashboard under Configuración > Integraciones, section E-COMMERCE 3DSECURE:

Field	Purpose
Url de Webhook	Receives the transaction result as a webhook
Url de redirección	Redirects the customer after payment completes

INFO

Both URLs must use HTTPS and include the protocol (e.g., https://mysite.com/result).

Create a checkout

POST /api/v1/checkout

Send your API key, an external identifier, items, and the total amount.

Request:

{
  "apiKey": "123ABC0-123ABC0-123ABC0-123ABC0",
  "externalId": "ORD-001",
  "items": [
    "Product 1",
    "Product 2",
    "Product 3"
  ],
  "total": 1000,
  "rates": [3, 6]
}

Field	Type	Required	Description
`apiKey`	string	✅	Your API key
`externalId`	string	✅	Your identifier for this checkout
`items`	array	✅	List of item names
`total`	number	✅	Amount in MXN
`rates`	array	—	Available MSI installment options (e.g., `[3, 6, 12]`)

Response:

{
  "checkoutId": "e8bfb912-c51a-4c62-bb22-876f1f9cc6d1",
  "externalId": "ORD-001",
  "total": "1000.00",
  "items": ["Product 1", "Product 2", "Product 3"],
  "rates": [3, 6],
  "description": "Example",
  "createdAt": "2024-06-12T03:07:25.049Z",
  "updatedAt": "2024-06-12T03:07:25.049Z"
}

Create the payment form URL

Concatenate the checkoutId from the response to the base URL:

Environment	Payment form URL
Dev	`https://test.paywith.billpocket.com/checkout/{checkoutId}`
Live	`https://paywith.billpocket.com/checkout/{checkoutId}`

Share this URL with your customer to open the hosted 3DS payment form. Use test cards for Dev environment testing.

Get checkout details

GET /api/v1/checkout/detail/{checkoutId}?apiKey={apiKey}

Retrieve the status and details of a previously created checkout.

Response:

{
  "checkout": {
    "items": ["Product 1", "Product 2"],
    "rates": [3, 6],
    "externalId": "ORD-001",
    "total": "1000.00",
    "createdAt": "2024-06-12T01:33:36.593Z",
    "updatedAt": "2024-06-12T01:34:33.001Z"
  },
  "transaction": {
    "status": 1,
    "message": "APROBADA",
    "opId": "128840",
    "txnISOCode": "00",
    "authNumber": "BP9274",
    "ticketUrl": "305214b8c6c5a689118454a69b2214927d5ddc52",
    "maskedPAN": "401200******0071"
  }
}

Next steps

Set up a webhook to receive transaction results

Review the Checkout API reference

Use test cards to simulate 3DS scenarios

Got a suggestion on this documentation? Contact us.

Requirements#

Environments#

Configure webhook and redirect URLs#

Create a checkout#

Create the payment form URL#

Get checkout details#

Next steps#

Requirements

Environments

Configure webhook and redirect URLs

Create a checkout

Create the payment form URL

Get checkout details

Next steps