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

1. Tokenization: Card data is securely tokenized

2. Authorization: Payment is authorized and funds are held

3. 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": "[e-mail]",
    "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": "[e-mail]",
    "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"
  }
}

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": "[e-mail]",
    "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": "[e-mail]",
    "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

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": "[e-mail]",
      "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": "[e-mail]",
      "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:

1. Capture: Collect the authorized amount (or less)

2. Authorization Void: Cancel the authorization

3. 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)	No
Use Case	Variable amounts, pre-auth	Fixed amounts, direct sales
Expiration	7 days typically	N/A (already collected)