API Reference

Checkout API

Complete API reference for the Hosted Checkout integration.

Endpoints

POST/api/v1/checkout

Create checkout session

GET/api/v1/checkout/{session_id}

Get session details

POST/api/v1/checkout/process

Process payment for session

POST/api/v1/checkout/{session_id}/cancel

Cancel checkout session

Create Checkout Session

POST/api/v1/checkout

Creates a new checkout session and returns a URL for the hosted checkout page.

Headers

Header	Required	Description
`X-API-Key`	Yes	Your API key
`Content-Type`	Yes	application/json

Request Body

Field	Type	Required	Description
`merchant_id`	string	No	Automatically set from your API key. Do not send this field.
`amount`	number	Yes	Payment amount (must be greater than 0)
`currency`	string	Yes	ISO 4217 currency code (BRL, PEN, COP, CLP, MXN, USD, ARS)
`country`	string	Yes	ISO 3166-1 alpha-3 country code (BRA, PER, COL, CHL, MEX, ECU, ARG)
`success_url`	string	Yes	URL to redirect after successful payment
`cancel_url`	string	Yes	URL to redirect if customer cancels
`notification_url`	string	No	Webhook URL for payment notifications
`description`	string	No	Description shown to customer
`expires_in_minutes`	number	No	Session expiration in minutes (default: 30, min: 5, max: 1440)
`customer`	object	No	Pre-fill customer data (see below)
`order_number`	string	No	Your external order/reference ID. Returned as `reference_id` in webhooks so you can match payments to your orders.
`metadata`	object	No	Custom key-value pairs returned in webhooks

Automatic Payment Method Selection

Cashier automatically determines which payment methods to display based on the country and your merchant configuration. You don't need to specify a method_code - just send the country and currency, and the checkout page will show all available methods for that market.

Customer Object (Optional)

Pre-fill customer information on the checkout page:

Field	Type	Description
`name`	string	Customer full name
`email`	string	Customer email address
`document`	string	Customer document number
`phone`	string	Customer phone number

Example Request

create-session.sh

curl -X POST "https://cashier.flowpayment.net/api/v1/checkout" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "amount": 150.00,
    "currency": "BRL",
    "country": "BRA",
    "description": "Order #12345",
    "order_number": "ORD-12345",
    "success_url": "https://your-site.com/success",
    "cancel_url": "https://your-site.com/cancel",
    "notification_url": "https://your-site.com/webhooks",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@example.com"
    }
  }'

Note

The merchant_id is automatically set from your API key. You don't need to include it in the request body.

Success Response (200)

success-response.json

{
  "success": true,
  "status": "redirect",
  "session_id": "cs_abc123xyz",
  "checkout_url": "https://cashier-checkout.s-interio.com/checkout/cs_abc123xyz",
  "expires_at": "2026-01-04T13:00:00Z"
}

Status field

The status: "redirect" indicates the session was created and the customer must be redirected to checkout_url. The success: true confirms the API call succeeded. The payment itself has not been completed yet — the final payment status will arrive via webhook.

Error Response (4xx)

error-response.json

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "amount must be greater than 0"
  }
}

Get Checkout Session

GET/api/v1/checkout/{session_id}

Retrieves details of an existing checkout session.

Example Request

bash

curl -X GET "https://cashier.flowpayment.net/api/v1/checkout/cs_abc123xyz"

Success Response

session-details.json

{
  "id": "cs_abc123xyz",
  "merchant_id": "your_merchant_id",
  "merchant_name": "Your Store Name",
  "amount": 150.00,
  "currency": "BRL",
  "country": "BRA",
  "description": "Order #12345",
  "customer": {
    "name": "Joao Silva",
    "email": "joao@example.com"
  },
  "available_methods": [
    {
      "id": "pix",
      "type": "pix",
      "name": "PIX",
      "enabled": true,
      "flow_type": "embedded",
      "required_fields": [
        { "field": "document", "type": "cpf", "label": "CPF", "required": true }
      ]
    },
    {
      "id": "card",
      "type": "card",
      "name": "Credit Card",
      "enabled": true,
      "flow_type": "redirect"
    },
    {
      "id": "boleto",
      "type": "boleto",
      "name": "Boleto",
      "enabled": true,
      "flow_type": "embedded",
      "required_fields": [
        { "field": "name", "type": "text", "label": "Full Name", "required": true },
        { "field": "document", "type": "cpf", "label": "CPF", "required": true }
      ]
    }
  ],
  "success_url": "https://your-site.com/success",
  "cancel_url": "https://your-site.com/cancel",
  "operation_type": "payin",
  "status": "pending",
  "payment_status": null,
  "payment_id": null,
  "expires_at": "2026-01-04T13:00:00Z",
  "created_at": "2026-01-04T12:00:00Z"
}

Field	Description
`status`	Primary status field. Returns the payment status when a payment exists (`pending`, `processing`, `success`, `failed`, `cancelled`, `expired`), or the session status when no payment has been initiated yet.
`payment_status`	Payment-level status (same values as above). `null` if no payment has been initiated.
`payment_id`	Payment intent ID (`pi_xxx`). `null` if no payment has been initiated.

Process Payment

POST/api/v1/checkout/process

Process payment for a checkout session.

Internal Endpoint

This endpoint is used internally by the hosted checkout page. You typically don't need to call it directly - redirect customers to the checkout_url returned when creating a session.

Request Body

Field	Type	Required	Description
`session_id`	string	Yes	Checkout session ID (cs_xxx)
`payment_method`	string	Yes	Payment method selected by customer (e.g., "pix", "card", "bank_transfer")
`customer`	object	Yes	Customer information (name, email, document)
`card`	object	No	Card details (required for card payments)

Card Object (for card payments)

Field	Type	Description
`number`	string	Card number (13-19 digits)
`holder_name`	string	Cardholder name
`expiry_month`	string	Expiration month (MM)
`expiry_year`	string	Expiration year (YYYY)
`cvv`	string	Security code (3-4 digits)

Example Request (PIX)

process-pix.sh

curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/process" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_your_api_key" \
  -d '{
    "session_id": "cs_abc123xyz",
    "payment_method": "pix",
    "customer": {
      "name": "Joao Silva",
      "email": "joao@example.com",
      "document": "12345678909"
    }
  }'

Success Response (PIX)

pix-response.json

{
  "success": true,
  "payment_id": "pi_xyz789abc",
  "status": "pending",
  "pix_code": "00020126360014br.gov.bcb.pix...",
  "pix_qr_code": "https://api.provider.com/qr/abc123.png"
}

Success Response (Card with 3DS redirect)

card-response.json

{
  "success": true,
  "payment_id": "pi_xyz789abc",
  "status": "processing",
  "redirect_url": "https://3ds.provider.com/auth/abc123"
}

Error Response

error.json

{
  "success": false,
  "status": "failed",
  "error_message": "Card declined by issuer"
}

Cancel Checkout Session

POST/api/v1/checkout/{session_id}/cancel

Cancels a pending checkout session. Cannot cancel completed sessions.

Example Request

bash

curl -X POST "https://cashier.flowpayment.net/api/v1/checkout/cs_abc123xyz/cancel"

Success Response

json

{
  "success": true,
  "message": "Checkout session cancelled"
}

Session Status

pending

Session created, awaiting customer

processing

Payment is being processed

completed

Payment successful

failed

Payment failed

expired

Session expired before completion

cancelled

Session was cancelled

Error Codes

Code	HTTP	Description
`UNAUTHORIZED`	`401`	Invalid or missing API key
`VALIDATION_ERROR`	`400`	Invalid request parameters
`MERCHANT_NOT_FOUND`	`404`	Merchant ID not found
`MERCHANT_INACTIVE`	`403`	Merchant account is inactive
`SESSION_NOT_FOUND`	`404`	Checkout session not found
`SESSION_EXPIRED`	`410`	Checkout session has expired
`COUNTRY_NOT_SUPPORTED`	`400`	Country not available for this merchant
`RATE_LIMIT_EXCEEDED`	`429`	Too many requests

Idempotency

To prevent duplicate checkouts, include an X-Idempotency-Key header:

bash

curl -X POST "https://cashier.flowpayment.net/api/v1/checkout" \
  -H "X-API-Key: your_api_key" \
  -H "X-Idempotency-Key: unique_request_id_12345" \
  -d '{ ... }'

If you send the same idempotency key within 24 hours, you'll receive the same response without creating a new session.

Rate Limits

Endpoint	Limit
`POST /api/v1/checkout`	100 requests/minute
`GET /api/v1/checkout/{id}`	300 requests/minute

Testing

Use sandbox mode for testing by including environment: "sandbox" in your request.

Sandbox Mode

No real charges are made. Use test credentials provided in your dashboard.