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 must be 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"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-07-26T17:27:16.000Z",
      "strategies": []
    }
  }
}

Failed Payment Response (200)

{
  "status": "success",
  "message": "Payment failed",
  "data": {
    "transaction_info": {
      "type": "payment_response",
      "reference_code": "1753550023570",
      "transaction_id": "0001755176590033234494",
      "request_id": "6de98d6d-1a49-438e-a648-23644c5856f1",
      "status": "Declined",
      "created_at": "2025-08-14T13:03:15.419Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 10001,
        "currency": "BRL"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-08-14T13:03:14.000Z",
      "strategies": []
    },
    "error_info": {
      "reason": "InsufficientFunds",
      "message": "Transaction failed"
    }
  }
}

Error Response (400/500)

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

Response Fields

transaction_info

Field
Type
Description

type

String

Response type (payment_response, authorization_response, etc.)

reference_code

String

Merchant reference code from request

transaction_id

String

Unique transaction identifier generated by Firstoken

request_id

String

Unique request identifier

status

String

Transaction status (Collected, Declined, Pending, etc.)

response_code

String

Internal response code

created_at

String

Transaction creation timestamp (ISO 8601)

order_info

Field
Type
Description

amount_details.authorized_amount

Number

Authorized amount

amount_details.currency

String

Transaction currency

risk_info

Field
Type
Description

status

String

Antifraud status: Approved, Rejected, Pending

date

String

Date of antifraud evaluation (ISO 8601)

strategies

Array

Array of antifraud strategies applied (see Strategies section)

error_info (present when transaction fails)

Field
Type
Description

reason

String

Failure reason (InsufficientFunds, InvalidCard, etc.)

message

String

Human-readable error message

Antifraud Strategies

The strategies array contains objects with antifraud strategies that were applied to the transaction. Each strategy object contains:

Field
Type
Description

type

String

Strategy type (VerificationCode ,DocumentScan ,ManualVerification ,CollectAuthRecovery ")

link

String

Reference link for strategy details

Note: Strategies must be configured in your KOIN account to appear in responses. If no strategies are configured, the array will be empty [].

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_{{$guid}}"
    },
    "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": "Generic"
      }
    ],
    "device_info": {
      "ip_address": "192.168.1.100"
    }
  }'
PreviousPayments API - KOINNextAuthorization

Last updated

Was this helpful?