Direct Payments

Process payments directly via API for custom checkout integrations.

Overview

The Direct Payments API allows you to build your own checkout experience while using Cashier to process the payment. This gives you full control over the UI and user experience.

Tip: For a faster integration, consider using Hosted Checkout which handles the payment UI for you.

Create Payment

POST/cashier/cashier/payment

Creates a new payment and returns the payment details including redirect URL or PIX code.

Request Body

Parameter	Type	Required	Description
`payment_method`	string	Yes	"pix" or "card"
`amount`	number	Yes	Payment amount (e.g., 100.00)
`currency`	string	Yes	Currency code (e.g., "BRL")
`country`	string	Yes	Country code (e.g., "BRA")
`customer`	object	Yes	Customer information
`description`	string	No	Payment description
`notification_url`	string	No	Webhook URL for notifications
`card`	object	Conditional	Required for card payments

Customer Object

Field	Type	Description
`name`	string	Full name
`email`	string	Email address
`document`	string	CPF/CNPJ (Brazil)
`phone`	string	Phone number (optional)

PIX Payment

PIX is Brazil's instant payment system. When you create a PIX payment, you'll receive a QR code and copy-paste code that the customer uses to complete the payment.

Example Request

Create PIX Payment

bash

curl -X POST https://cashier.flowpayment.net/cashier/cashier/payment \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "pix",
    "amount": 100.00,
    "currency": "BRL",
    "country": "BRA",
    "description": "Order #12345",
    "customer": {
      "name": "Maria Silva",
      "email": "maria@example.com",
      "document": "12345678900"
    },
    "notification_url": "https://yoursite.com/webhooks/cashier"
  }'

Example Response

Response (201 Created)

json

{
  "payment_id": "pi_abc123xyz789",
  "status": "pending",
  "payment_method": "pix",
  "amount": 100.00,
  "currency": "BRL",
  "pix_code": "00020126580014br.gov.bcb.pix0136...",
  "pix_qr_code_base64": "data:image/png;base64,iVBORw0KGgoAAAANSU...",
  "expires_at": "2024-12-12T15:30:00Z"
}

Note: PIX payments typically expire in 30 minutes. Make sure to display the expiration time to your customer.

Card Payment

Process credit and debit card payments. Card payments may require 3D Secure authentication, in which case you'll receive a redirect URL.

Card Object

Field	Type	Description
`number`	string	Card number (no spaces)
`holder_name`	string	Name on card
`expiry_month`	string	2-digit month (e.g., "12")
`expiry_year`	string	4-digit year (e.g., "2025")
`cvv`	string	3 or 4 digit security code
`installments`	number	Number of installments (1-12)

Example Request

Create Card Payment

bash

curl -X POST https://cashier.flowpayment.net/cashier/cashier/payment \
  -H "X-API-Key: sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_method": "card",
    "amount": 250.00,
    "currency": "BRL",
    "country": "BRA",
    "description": "Order #12345",
    "customer": {
      "name": "Carlos Santos",
      "email": "carlos@example.com",
      "document": "98765432100"
    },
    "card": {
      "number": "4111111111111111",
      "holder_name": "CARLOS SANTOS",
      "expiry_month": "12",
      "expiry_year": "2025",
      "cvv": "123",
      "installments": 1
    },
    "notification_url": "https://yoursite.com/webhooks/cashier"
  }'

Example Response (Success)

Response (201 Created)

json

{
  "payment_id": "pi_def456uvw123",
  "status": "success",
  "payment_method": "card",
  "amount": 250.00,
  "currency": "BRL",
  "card_brand": "visa",
  "card_last_four": "1111",
  "authorization_code": "123456"
}

Example Response (3DS Required)

Response (201 Created - 3DS)

json

{
  "payment_id": "pi_def456uvw123",
  "status": "pending_3ds",
  "payment_method": "card",
  "amount": 250.00,
  "currency": "BRL",
  "redirect_url": "https://3ds.provider.com/auth/xyz123",
  "return_url": "https://yoursite.com/payment/complete"
}

Security: Never log or store full card numbers. Card data should only be transmitted over HTTPS and handled in PCI-compliant environments.

Get Payment Status

GET/cashier/cashier/status/{merchant_id}/{payment_id}

Retrieves the current status of a payment.

Example Request

Get Payment Status

bash

curl https://cashier.flowpayment.net/cashier/cashier/status/merchant_001/pi_abc123xyz789 \
  -H "X-API-Key: sk_live_your_api_key"

Example Response

Response (200 OK)

json

{
  "payment_id": "pi_abc123xyz789",
  "merchant_id": "merchant_001",
  "status": "success",
  "payment_method": "pix",
  "amount": 100.00,
  "currency": "BRL",
  "paid_at": "2024-12-12T15:05:30Z",
  "created_at": "2024-12-12T15:00:00Z"
}

Payment Status

Status	Description
`pending`	Payment created, awaiting customer action
`pending_3ds`	Card payment requires 3DS authentication
`processing`	Payment is being processed by the provider
`success`	Payment completed successfully
`failed`	Payment failed (declined, error, etc.)
`cancelled`	Payment was cancelled
`expired`	Payment expired (PIX timeout)
`refunded`	Payment was refunded

Error Handling

When a payment fails, the API returns an error with details about what went wrong.

Common Errors

400 Bad Request

Invalid request parameters (missing fields, invalid amount, etc.)

401 Unauthorized

Invalid or missing API key

422 Unprocessable Entity

Payment declined by provider (insufficient funds, invalid card, etc.)

500 Internal Server Error

Server error - contact support if persistent

Error Response Example

Error Response (422)

json

{
  "detail": "Card declined: insufficient funds",
  "error_code": "card_declined",
  "payment_id": "pi_abc123xyz789"
}