Skip to main content
POST
/
v1
/
charges
Create a new charge
curl --request POST \
  --url https://api-global.fastpaybrasil.com/v1/charges \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 10,
  "currency": "USD",
  "customer": {
    "id": "2RhQg9M7ZCg3X3nMb9W1kX8Q",
    "name": "John Doe",
    "email": "[email protected]",
    "phone": "+1234567890",
    "document": {
      "type": "dni",
      "id": "12345678900"
    },
    "address": {
      "country": "USA"
    },
    "ipAddress": "127.0.0.1"
  },
  "paymentMethod": {
    "type": "credit_card",
    "number": "1111222233334444",
    "holderName": "John Doe",
    "expirationMonth": "10",
    "expirationYear": "2025",
    "cvv": "123",
    "installments": 1,
    "threeDSMode": "managed"
  },
  "items": [
    {
      "title": "Shoes",
      "description": "Nike Shoes",
      "unit_price": 199.99,
      "quantity": 1
    }
  ],
  "trackingInfo": {
    "trackingCode": "TRK123456789",
    "shippingProvider": "FedEx",
    "trackingUrl": "https://tracking.com/TRK123456789",
    "trackingStatus": "on_the_way"
  },
  "metadata": {
    "order_id": "ORD-123",
    "product_id": "PROD-456"
  },
  "postbackUrl": "https://merchant.com/webhooks/charge-status",
  "split": [
    {
      "merchantId": "2vorkDcXyvzifL63YX09S9VqcnI",
      "percentage": 10
    }
  ]
}
'
{
  "id": "2vorkDcXyvzifL63YX09S9VqcnI",
  "status": "pending",
  "paymentDetails": {
    "firstSix": "123456",
    "lastFour": "7890",
    "expirationMonth": "08",
    "expirationYear": "2024",
    "holderName": "John Doe",
    "installments": 3
  },
  "reason": "Insufficient funds"
}

Authorizations

​
Authorization
string
header
required

HTTP Basic authentication. Use your secret key as the username and an empty string as password. The API key should be base64 encoded in the format 'username:' when sending the Authorization header.

Body

application/json
​
amount
number
required

The amount to charge in the currency unit, not cents. (e.g., 10 for 10 BRL)

Required range: x >= 1
Example:

10

​
currency
string
required

The ISO 4217 currency code. (e.g., BRL, USD, EUR)

Example:

"USD"

​
customer
object
required

Customer data. Provide id to reference an existing customer (all other fields become optional), or provide name + email (or phone) to create/look up a customer inline.

​
paymentMethod
Credit Card · object
required
​
items
object[]
required

List of charge items.

​
shippingAddress
object

Shipping address details. Required for merchants selling physical goods.

​
trackingInfo
object

Shipping tracking details.

​
metadata
object

Additional metadata to store with the charge.

Example:
{
  "order_id": "ORD-123",
  "product_id": "PROD-456"
}
​
postbackUrl
string<uri>

Optional URL that receives asynchronous webhook notifications for the charge's lifecycle events AFTER creation. This URL is NOT used for the synchronous create response.

Events delivered to this URL:

  • PIX charges: charge.pending (QR code created), charge.paid
  • Credit card charges: charge.paid, charge.refunded, charge.updated

The payload format is identical to the registered webhook endpoint format (id, event, livemode, data with the full charge object). Retry logic applies the same exponential backoff as endpoint webhooks.

Example:

"https://merchant.com/webhooks/charge-status"

​
split
object[]

Array of merchants and percentages participating in Split

Response

The charge has been successfully created

​
id
string
required

The unique identifier of the created charge

Example:

"2vorkDcXyvzifL63YX09S9VqcnI"

​
status
enum<string>
required

The status of the charge

Available options:
paid,
pending,
refused,
failed
Example:

"pending"

​
paymentDetails
Credit Card · object
required

Additional payment details specific to the payment method

​
reason
string | null
required

The reason for charge status (especially for refused charges)

Example:

"Insufficient funds"