Checkout Sessions

Create hosted checkout sessions to accept payments without building your own checkout UI.

How It Works

Create a Checkout Session

Your server creates a checkout session via API

Redirect Customer

Redirect your customer to the checkout_url

Customer Pays

Customer selects payment method and completes payment

Handle Result

Customer is redirected to success_url or cancel_url

Create Checkout Session

POST/api/v1/checkout

Creates a new checkout session and returns a URL to redirect your customer.

Request Body

Parameter	Type	Required	Description
`amount`	number	Yes	Payment amount (e.g., 100.00)
`currency`	string	Yes	Currency code (e.g., "BRL")
`success_url`	string	Yes	URL to redirect after successful payment
`cancel_url`	string	Yes	URL to redirect if customer cancels
`country`	string	No	Country code (default: "BRA")
`description`	string	No	Payment description
`customer`	object	No	Customer info (name, email, document)
`notification_url`	string	No	Webhook URL for payment notifications
`metadata`	object	No	Custom key-value pairs

Example Request

Create Checkout Session

bash

curl -X POST https://cashier.flowpayment.net/api/v1/checkout \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 150.00,
    "currency": "BRL",
    "country": "BRA",
    "description": "Order #12345",
    "customer": {
      "name": "John Doe",
      "email": "john@example.com",
      "document": "12345678900"
    },
    "success_url": "https://yoursite.com/success?session_id={SESSION_ID}",
    "cancel_url": "https://yoursite.com/cancel",
    "notification_url": "https://yoursite.com/webhooks/cashier"
  }'

Example Response

Response (201 Created)

json

{
  "id": "cs_abc123xyz789",
  "checkout_url": "https://cashier-checkout.s-interio.com/checkout/cs_abc123xyz789",
  "expires_at": "2024-12-12T15:30:00Z"
}

Get Checkout Session

GET/api/v1/checkout/{session_id}

Retrieves the details of an existing checkout session.

Example Request

Get Checkout Session

bash

curl https://cashier.flowpayment.net/api/v1/checkout/cs_abc123xyz789 \
  -H "X-API-Key: sk_live_your_api_key"

Example Response

Response (200 OK)

json

{
  "id": "cs_abc123xyz789",
  "merchant_id": "merchant_001",
  "amount": 150.00,
  "currency": "BRL",
  "country": "BRA",
  "description": "Order #12345",
  "status": "pending",
  "available_methods": [
    {
      "id": "pix",
      "type": "pix",
      "name": "PIX",
      "provider": "sfp",
      "enabled": true
    },
    {
      "id": "card",
      "type": "card",
      "name": "Credit/Debit Card",
      "provider": "izipay",
      "enabled": true
    }
  ],
  "customer": {
    "name": "John Doe",
    "email": "john@example.com"
  },
  "success_url": "https://yoursite.com/success",
  "cancel_url": "https://yoursite.com/cancel",
  "expires_at": "2024-12-12T15:30:00Z",
  "created_at": "2024-12-12T15:00:00Z"
}

Cancel Checkout Session

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

Cancels an active checkout session.

Cancel Session

bash

curl -X POST https://cashier.flowpayment.net/api/v1/checkout/cs_abc123xyz789/cancel \
  -H "X-API-Key: sk_live_your_api_key"

Session Status

Status	Description
`pending`	Session created, waiting for customer
`processing`	Payment is being processed
`completed`	Payment successful
`failed`	Payment failed
`cancelled`	Session was cancelled
`expired`	Session expired (30 min default)