Payments - Complete Flow

Overview

The Payments endpoint processes a complete payment transaction with automatic tokenization, authorization, and capture in a single API call. This is the most common endpoint for direct sales where you want immediate payment collection.

POST /v1/payments/

What Happens Internally

Client Request → Firstoken API → [Tokenization + Authorization + Capture] → Response

  1. Tokenization: Card data is securely tokenized

  2. Authorization: Payment is authorized with the token

  3. Capture: Payment is automatically captured

  4. Response: Single response with the complete transaction result

Request Body

Minimal Required Fields

{
  "transaction_info": {
    "type": "payment",
    "reference_code": "1753550023570"
  },
  "card": {
    "number": "4225289837059229",
    "expiration_date": "01/2030",
    "security_code": "123",
    "holder": "John Doe Jones"
  },
  "order_info": {
    "amount_details": {
      "total_amount": 1000,
      "currency": "BRL",
      "items_amount": 1000
    },
    "installments": 1,
    "descriptor": "Test Payment"
  },
  "cardholder_info": {
    "first_name": "John",
    "last_name": "Doe",
    "document": {
      "type": "CPF",
      "number": "54672396002",
      "nationality": "BR"
    },
    "country": "BR",
    "address_1": "123 Main St",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "04001-000",
    "email": "john_autoaccept@test.com",
    "phone_number": "4158880000",
    "phone_type": "Mobile",
    "phone_area_code": "22"
  },
  "bill_to": {
    "id": "1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "document": {
      "type": "CPF",
      "number": "54672396002",
      "nationality": "BR"
    },
    "country": "BR",
    "address_1": "123 Main St",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "04001-000",
    "email": "test@cybs.com",
    "phone_number": "4158880000",
    "phone_type": "Mobile",
    "phone_area_code": "22",
    "profile": "1"
  },
  "line_items": [
    {
      "category": {
        "id": "1",
        "name": "Category 1"
      },
      "id": "1",
      "name": "Item 1",
      "price": 1500,
      "quantity": 1,
      "type": "Generic"
    }
  ],
  "device_info": {
    "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
    "ip_address": "127.0.0.1"
  }
}

Complete Request with All Fields

{
  "transaction_info": {
    "type": "payment",
    "reference_code": "1753550698549"
  },
  "card": {
    "number": "4225289837059229",
    "expiration_date": "01/2030",
    "security_code": "123",
    "holder": "John Doe Jones"
  },
  "order_info": {
    "amount_details": {
      "total_amount": 1000,
      "currency": "BRL",
      "items_amount": 1000,
      "shipping_amount": 20,
      "fee_amount": 10
    },
    "installments": 1,
    "descriptor": "Test Payment"
  },
  "cardholder_info": {
    "first_name": "John",
    "last_name": "Doe",
    "document": {
      "type": "CPF",
      "number": "54672396002",
      "nationality": "BR"
    },
    "gender": "MALE",
    "country": "BR",
    "address_1": "123 Main St",
    "address_2": "address 2",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "04001-000",
    "birth_date": "2025-07-01",
    "email": "john_autoaccept@test.com",
    "phone_number": "4158880000",
    "phone_type": "Mobile",
    "phone_country_code": "58",
    "phone_area_code": "22"
  },
  "bill_to": {
    "id": "1234567890",
    "first_name": "John",
    "last_name": "Doe",
    "document": {
      "type": "CPF",
      "number": "54672396002",
      "nationality": "BR"
    },
    "gender": "MALE",
    "country": "BR",
    "address_1": "123 Main St",
    "address_2": "address 2",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "04001-000",
    "birth_date": "2025-07-01",
    "email": "test@cybs.com",
    "phone_number": "4158880000",
    "phone_type": "Mobile",
    "phone_area_code": "22",
    "profile": "1"
  },
  "line_items": [
    {
      "category": {
        "id": "1",
        "name": "Category 1"
      },
      "discount_amount": 10,
      "id": "1",
      "name": "Item 1",
      "price": 1500,
      "quantity": 1,
      "seller_id": "seller id",
      "service_date": "2025-07-01",
      "type": "Generic"
    }
  ],
  "shipping_info": {
    "country": "BR",
    "address_1": "123 Main St",
    "address_2": "address 2",
    "city": "Sao Paulo",
    "state": "SP",
    "postal_code": "04001-000",
    "by": "DHL",
    "date": "2021-01-01T00:00:00.000Z",
    "type": "EXPRESS",
    "price": 1000
  },
  "device_info": {
    "ip_address": "127.0.0.1"
  }
}

Field Specifications

transaction_info (Required)

Field
Type
Required
Description

type

String

Yes

Must be "payment"

reference_code

String

Yes

Merchant reference code

card (Required)

Field
Type
Required
Description

number

String

Yes

Card number

expiration_date

String

Yes

Card expiration (MM/YYYY format)

security_code

String

Yes

CVV/CVC code (3-4 digits)

holder

String

Yes

Cardholder name as it appears on card

order_info (Required)

Field
Type
Required
Description

amount_details.total_amount

Number

Yes

Total transaction amount

amount_details.currency

String

Yes

Currency code (BRL, USD, etc.)

amount_details.items_amount

Number

Yes

Sum of line items amount

amount_details.shipping_amount

Number

No

Shipping cost

amount_details.fee_amount

Number

No

Additional fees

installments

Number

Yes

Number of installments

descriptor

String

Yes

Payment descriptor

cardholder_info (Required)

Field
Type
Required
Description

first_name

String

Yes

First name

last_name

String

Yes

Last name

document.type

String

Yes

Document type (CPF, CNPJ)

document.number

String

Yes

Document number

document.nationality

String

Yes

Document nationality (BR)

country

String

Yes

Country code

address_1

String

Yes

Primary address

city

String

Yes

City name

state

String

Yes

State code

postal_code

String

Yes

Postal code

email

String

Yes

Email address

phone_number

String

Yes

Phone number

phone_type

String

No

Phone type (Mobile, Home, Work)

phone_area_code

String

Yes

Area code

gender

String

No

Gender (MALE, FEMALE, OTHER)

birth_date

String

No

Birth date (YYYY-MM-DD)

address_2

String

No

Secondary address

phone_country_code

String

No

Phone country code

bill_to (Required)

Field
Type
Required
Description

id

String

No

Customer identifier

profile

String

No

Customer profile

All other fields

Various

Same as cardholder_info

Same requirements

line_items (Required)

Field
Type
Required
Description

id

String

Yes

Item identifier

name

String

Yes

Item name

price

Number

Yes

Item price

quantity

Number

Yes

Item quantity

type

String

No

Item type (Physical, Digital, Service, Generic)

category.id

String

No

Category identifier

category.name

String

No

Category name

seller_id

String

No

Seller identifier

service_date

String

No

Service date

discount_amount

Number

No

Discount applied

device_info (Recommended)

Field
Type
Required
Description

ip_address

String

No

Customer IP address

shipping_info (Optional)

Field
Type
Required
Description

country

String

No

Shipping country

address_1

String

No

Shipping address

city

String

No

Shipping city

state

String

No

Shipping state

postal_code

String

No

Shipping postal code

by

String

No

Shipping carrier

date

String

No

Expected delivery date

type

String

No

Shipping type (STANDARD, EXPRESS)

price

Number

No

Shipping cost

Response Format

Success Response (200)

{
  "status_code": 200,
  "status": "Success",
  "desc": "Payment processed successfully",
  "data": {
    "transaction_info": {
      "type": "payment_response",
      "reference_code": "1753550831362",
      "transaction_id": "0001753550831987788592",
      "request_id": "6a67ceba-9c66-4c80-b567-6f821cff007b",
      "status": "Collected",
      "response_code": "6344942",
      "created_at": "2025-07-26T17:27:17.931Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 1000,
        "currency": "BRL"
      }
    }
  }
}

Error Response (400/500)

{
  "status": "Fail",
  "message": "Invalid request",
  "data": {
    "code": 400,
    "description": "Invalid card data."
  }
}

cURL Example

curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "transaction_info": {
      "type": "payment",
      "reference_code": "ref_' $(date +%s) '"
    },
    "card": {
      "number": "4225289837059229",
      "expiration_date": "01/2030",
      "security_code": "123",
      "holder": "João Silva"
    },
    "order_info": {
      "amount_details": {
        "total_amount": 1000,
        "currency": "BRL",
        "items_amount": 1000
      },
      "installments": 1,
      "descriptor": "Compra Online"
    },
    "cardholder_info": {
      "first_name": "João",
      "last_name": "Silva",
      "document": {
        "type": "CPF",
        "number": "12345678901",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "04001-000",
      "email": "joao@example.com",
      "phone_number": "11987654321",
      "phone_type": "Mobile",
      "phone_area_code": "11"
    },
    "bill_to": {
      "id": "customer_123",
      "first_name": "João",
      "last_name": "Silva",
      "document": {
        "type": "CPF",
        "number": "12345678901",
        "nationality": "BR"
      },
      "country": "BR",
      "address_1": "Rua das Flores, 123",
      "city": "São Paulo",
      "state": "SP",
      "postal_code": "04001-000",
      "email": "joao@example.com",
      "phone_number": "11987654321",
      "phone_type": "Mobile",
      "phone_area_code": "11",
      "profile": "regular"
    },
    "line_items": [
      {
        "category": {
              "id": "1",
              "name": "Category 1"
        },
        "id": "item_001",
        "name": "Produto Teste",
        "price": 1000,
        "quantity": 1,
        "type": "Physical"
      }
    ],
    "device_info": {
      "ip_address": "192.168.1.100"
    }
  }'
PreviousPayments API - KOINNextAuthorization

Last updated

Was this helpful?