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
v1/payments/transactions/{transactionId}	GET	Transaction Details - Get transaction last update

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	Reason	Description
Opened	-	The order was created and in progress
Authorized	-	The order was authorized
Collected	-	The order was created and paid for
Cancelled	-	The state of an Opened order that expired or was cancelled by calling cancellation operation
Voided	-	The state of an Authorized order that expired or was voided by calling cancellation operation
Failed	Rejected	The transaction was declined. The acquirer does not allow this transaction to be processed
Failed	InsufficientFunds	The transaction was declined because the card has insufficient funds. Please, try a different card
Failed	InvalidCard	The transaction was declined because the card details are invalid. Please, try again
Failed	Referred	The transaction was declined. The customer should contact their bank
Failed	ExpiredCard	The transaction was declined because the card is expired. Please, try a different card
Failed	InvalidConfiguration	The transaction was declined due to a processing error. Contact Firstoken for more details
Failed	Undefined	The transaction was declined due to an unexpected error
Failed	StolenCard	The transaction was declined because the card is reported as stolen, related to fraud. Please, try a different card
Failed	ConnectionRejected	The transaction was declined due to a processing error. The acquirer and supplier are working on it
Failed	InvalidData	The transaction was declined due to a processing error. Contact Firstoken for more details
Failed	Antifraud	The transaction was declined for antifraud

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