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

Tokenization: Card data is securely tokenized
Authorization: Payment is authorized with the token
Capture: Payment is automatically captured
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",
    "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
  }
}

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

Note: Use a Firstoken token instead of card details; simply apply the token directly as follow

Temporal token:

"{{08d40297-29d3-493e-b790-8e1085bc0a11: transaction}}"

Permanent token (you can use all schema token types) :
```
"{{419894dd-4211-409b-a31e-c76aba8da9f3: detokenize}}"
```

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

Shipping cost

amount_details.fee_amount

Number

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

Phone type (Mobile, Home, Work)

phone_area_code

String

Yes

Area code

gender

String

Gender (MALE, FEMALE, OTHER)

birth_date

String

Birth date (YYYY-MM-DD)

address_2

String

Secondary address

phone_country_code

String

Phone country code

bill_to (Required)

Field

Type

Required

Description

id

String

Customer identifier

profile

String

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

Item type must be Generic

category.id

String

Category identifier

category.name

String

Category name

seller_id

String

Seller identifier

service_date

String

Service date

discount_amount

Number

Discount applied

Device Info

Parameter

Type

Required

Description

ip_address

String

Yes

Customer's IP address

fingerprint_session_id*

String

Yes

A unique numerical ID generated for each user session on a website.

_{(*) The}_{fingerprint_session_id}_{is generated using a Koin script that is called from the webpage.}

shipping_info (Optional)

Field

Type

Required

Description

country

String

Shipping country

address_1

String

Shipping address

city

String

Shipping city

state

String

Shipping state

postal_code

String

Shipping postal code

by

String

Shipping carrier

date

String

Expected delivery date

type

String

Shipping type (STANDARD, EXPRESS)

price

Number

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 - KOIN NextAuthorization

Last updated 2 months ago

hashtagOverview

hashtagWhat Happens Internally

hashtagRequest Body

hashtagMinimal Required Fields

hashtagComplete Request with All Fields

hashtagField Specifications

hashtagtransaction_info (Required)

hashtagcard (Required)

hashtagNote: Use a Firstoken token instead of card details; simply apply the token directly as follow

hashtagorder_info (Required)

hashtagcardholder_info (Required)

hashtagbill_to (Required)

hashtagline_items (Required)

hashtagDevice Info

hashtagshipping_info (Optional)

hashtagResponse Format

hashtagSuccess Response (200)

hashtagFailed Payment Response (200)

hashtagError Response (400/500)

hashtagResponse Fields

hashtagtransaction_info

hashtagorder_info

hashtagrisk_info

hashtagerror_info (present when transaction fails)

hashtagAntifraud Strategies

hashtagcURL Example

Overview

What Happens Internally

Request Body

Minimal Required Fields

Complete Request with All Fields

Field Specifications

transaction_info (Required)

card (Required)

Note: Use a Firstoken token instead of card details; simply apply the token directly as follow

order_info (Required)

cardholder_info (Required)

bill_to (Required)

line_items (Required)

Device Info

shipping_info (Optional)

Response Format

Success Response (200)

Failed Payment Response (200)

Error Response (400/500)

Response Fields

transaction_info

order_info

risk_info

error_info (present when transaction fails)

Antifraud Strategies

cURL Example