Authorization

Overview

The Authorization endpoint authorizes a payment without capturing it. This is useful when you need to verify funds availability or when the final amount might change before capture. The funds are held on the customer's card but not yet collected.

POST /v1/payments/

What Happens Internally

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

Tokenization: Card data is securely tokenized
Authorization: Payment is authorized and funds are held
Response: Authorization details returned (capture required separately)

Request Body

The request format is identical to the Payment endpoint, but with "type": "authorization" instead of "type": "payment".

Minimal Required Fields

{
  "transaction_info": {
    "type": "authorization",
    "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": {
    "ip_address": "127.0.0.1",
    "fingerprint_session_id": "0a76c25669713d8d6d306ba8c21259b7",
  }
}

Complete Request with All Fields

{
  "transaction_info": {
    "type": "authorization",
    "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

All field specifications are identical to the Payment endpoint, except:

transaction_info.type must be "authorization"

Response Format

Success Response (200)

{
  "status_code": 200,
  "status": "Success", 
  "desc": "Authorization processed successfully",
  "data": {
    "transaction_info": {
      "type": "authorization_response",
      "reference_code": "1753550698549",
      "transaction_id": "0001753550699162992390",
      "request_id": "10cf95b7-746f-4fba-bb02-d7f53f64fb6c",
      "status": "Authorized",
      "response_code": "4389437",
      "created_at": "2025-07-26T17:25:06.759Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 1000,
        "currency": "BRL"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-07-26T17:25:06.000Z",
      "strategies": []
    }
  }
}

Failed Authorization Response (200)

{
  "status": "success",
  "message": "Authorization failed",
  "data": {
    "transaction_info": {
      "type": "authorization_response",
      "reference_code": "1753550023570",
      "transaction_id": "0001755131293054685902",
      "request_id": "6aaac7d1-3be3-4721-96a0-a8d5f5b607a9",
      "status": "Declined",
      "created_at": "2025-08-14T00:28:17.265Z"
    },
    "order_info": {
      "amount_details": {
        "authorized_amount": 10001,
        "currency": "BRL"
      }
    },
    "risk_info": {
      "status": "Approved",
      "date": "2025-08-14T00:28:16.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 (authorization_response, payment_response, etc.)

reference_code

String

Merchant reference code from request

transaction_id

String

Unique transaction identifier generated by KOIN

request_id

String

Unique request identifier

status

String

Transaction status (Authorized, 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 in cents

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": "authorization",
      "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": "Pre-autorização"
    },
    "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"
    }
  }'

Important Notes

Authorization Expiration

Typical Expiration: Authorizations expire after 7 days if not captured
Best Practice: Capture within 24-48 hours for best success rates

Next Steps After Authorization

After a successful authorization, you have three options:

Capture: Collect the authorized amount (or less)
Authorization Void: Cancel the authorization
Wait for Expiration: Authorization will automatically expire

Authorization vs Payment

Aspect

Authorization

Payment

Funds Collection

Holds funds only

Collects funds immediately

Customer Experience

Pending charge

Completed charge

Next Step Required

Yes (capture or reversal)

Use Case

Variable amounts, pre-auth

Fixed amounts, direct sales

Expiration

7 days typically

N/A (already collected)

PreviousPayments - Complete Flow NextCard Validation

Last updated 2 months ago

hashtagOverview

hashtagWhat Happens Internally

hashtagRequest Body

hashtagMinimal Required Fields

hashtagComplete Request with All Fields

hashtagField Specifications

hashtagResponse Format

hashtagSuccess Response (200)

hashtagFailed Authorization Response (200)

hashtagError Response (400/500)

hashtagResponse Fields

hashtagtransaction_info

hashtagorder_info

hashtagrisk_info

hashtagerror_info (present when transaction fails)

hashtagAntifraud Strategies

hashtagcURL Example

hashtagImportant Notes

hashtagAuthorization Expiration

hashtagNext Steps After Authorization

hashtagAuthorization vs Payment

Overview

What Happens Internally

Request Body

Minimal Required Fields

Complete Request with All Fields

Field Specifications

Response Format

Success Response (200)

Failed Authorization Response (200)

Error Response (400/500)

Response Fields

transaction_info

order_info

risk_info

error_info (present when transaction fails)

Antifraud Strategies

cURL Example

Important Notes

Authorization Expiration

Next Steps After Authorization

Authorization vs Payment