Payments API - KOIN

Overview

This API provides a comprehensive interface for processing payments through KOIN. This API offers multiple endpoints for different payment operations, from simple authorizations to complete payment flows with automatic tokenization and capture.

Key Features:

• Multiple Payment Flows: Choose between authorization-only or complete payment processing

• Advanced Integration: Full tokenization, authorization, and capture capabilities

• Flexible Operations: Support for capture, void, and reversal operations

• Comprehensive Data: Rich transaction data collection for optimal processing

Important: To use these payment endpoints, you must contact Firstoken to enable payment processing capabilities in your account.

Base URLs

• Production: https://api.firstoken.co/v1/payments/

• Sandbox: https://api.firstoken-staging.co/v1/payments/ (for testing only)

Authentication

All API requests require authentication using an API key in the x-api-key header:

curl -X POST https://api.firstoken.co/v1/payments/ \
  -H 'x-api-key: YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{...}'

Available Endpoints

Endpoint	Method	Description
/v1/payments/	POST	Complete Payment Flow - Tokenization + Authorization + Capture
/v1/payments/	POST	Authorization Only - Authorize payment without capture
/v1/payments/{transactionId}/capture	POST	Capture - Capture a previously authorized payment
/v1/payments/{transactionId}/refund	POST	Payment Refund - Refund a completed payment
/v1/payments/{transactionId}/void	POST	Authorization Void - Void an authorization

Transaction Types

The API supports different transaction types specified in the transaction_info.type field:

Type	Description	Use Case
payment	Complete payment flow (tokenization + auth + capture)	Direct sales, immediate collection
authorization	Authorization only	Pre-authorization, capture later
capture	Capture authorized amount	Complete pre-authorized payment
payment_refund	Void completed payment	Cancel completed transaction
authorization_void	Reverse authorization	Cancel authorization

Common Request Fields

transaction_info (Required for all requests)

{
  "type": "payment", // or "authorization", "capture", etc.
  "reference_code": "merchant_reference"
}

card (Required for payment/authorization)

{
  "number": "4225289837059229",
  "expiration_date": "01/2030",
  "security_code": "123",
  "holder": "John Doe Jones"
}

order_info (Required for payment/authorization)

{
  "amount_details": {
    "total_amount": 1000,
    "currency": "BRL",
    "items_amount": 1000
  },
  "installments": 1,
  "descriptor": "Payment Description"
}

cardholder_info (Required for payment/authorization)

{
  "first_name": "John",
  "last_name": "Doe",
  "document": {
    "type": "CPF",
    "number": "54672396002",
    "nationality": "BR"
  },
  "country": "BR",
  "address_1": "123 Main St",
  "city": "São Paulo",
  "state": "SP",
  "postal_code": "04001-000",
  "email": "[e-mail]",
  "phone_number": "4158880000",
  "phone_type": "Mobile",
  "phone_area_code": "22"
}

Status Codes

HTTP Code	Description
200	Success
400	Bad Request - Invalid request
403	Access Denied - Authentication failed
500	Internal Server Error

Transaction Status Values

Status	Description
Authorized	Payment authorized successfully
Collected	Payment completed (authorized and captured)
Pending	Transaction in progress
Voided	Transaction voided
Reversed	Authorization reversed
Failed	Transaction failed

Getting Started

1. Account Configuration: Our team will configure your account

2. API Keys: Create your sandbox and production API keys

3. Contact Firstoken: to request payment processing activation

4. Testing: Test integration using the sandbox environment

5. Go Live: Deploy to production after successful testing

---

Navigation

• Payments (Complete Flow) - One-call payment processing

• Authorization - Authorization-only transactions

• Capture - Capture authorized payments

• Payment Refund - Void completed payments

• Authorization Void - Reverse authorizations

• Testing Guide - Test cards, amounts, and scenarios