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	Yes	Your merchant identifier
`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)
`metadata`	object	No	Custom key-value pairs returned in webhooks

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",
    "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"
    },
    "metadata": {
      "order_id": "12345"
    }
  }'

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,
  "session_id": "cs_abc123xyz",
  "checkout_url": "https://cashier-checkout.s-interio.com/checkout/cs_abc123xyz",
  "expires_at": "2026-01-04T13:00:00Z"
}

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",
      "provider": "sfp",
      "method_code": "s-interio-mt-1",
      "enabled": true,
      "flow_type": "embedded",
      "required_fields": [
        { "field": "document", "type": "cpf", "label": "CPF", "required": true }
      ]
    },
    {
      "id": "card",
      "type": "card",
      "name": "Credit Card",
      "provider": "izipay",
      "method_code": "s-interio-mt-2",
      "enabled": true,
      "flow_type": "redirect"
    }
  ],
  "success_url": "https://your-site.com/success",
  "cancel_url": "https://your-site.com/cancel",
  "status": "pending",
  "expires_at": "2026-01-04T13:00:00Z",
  "created_at": "2026-01-04T12:00:00Z"
}

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)
`method_code`	string	Yes*	Payment method code (e.g., "s-interio-mt-1")
`customer`	object	Yes	Customer information (name, email, document)
`card`	object	No	Card details (required for card payments)

* Either method_code OR both provider + payment_method required

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" \
  -d '{
    "session_id": "cs_abc123xyz",
    "method_code": "s-interio-mt-1",
    "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.