Any modern payment gateway has a robust set of APIs (Application Programming Interfaces), along with clear documentation. These APIs allow mobile apps, websites, software platforms, and other devices to seamlessly call the payment gateway to conduct transactions and retrieve or send data.
This article covers how payment gateway APIs work, their components, and their role in ensuring secure, efficient financial transactions. We also end with examples of how basic transactions work.
What is a Payment Gateway API?
A payment gateway API is a set of protocols and tools that allow developers to integrate payment processing functionality into their applications. It acts as an intermediary between the business software and the financial institutions involved in the transaction, enabling the authorization and processing of payments.
How Payment Gateway APIs Work
- Initialization:
- The merchant’s website or application initializes the payment process by sending a payment request to the payment gateway API, including transaction details and customer information.
- Tokenization:
- The payment gateway API converts sensitive payment information into a secure token, which is then used to process the transaction without exposing sensitive data.
- Authentication:
- The payment gateway API authenticates the request using API keys or OAuth tokens to ensure it originates from a trusted source.
- Authorization:
- The API sends the transaction details to the acquiring bank (merchant’s bank), which forwards them to the issuing bank (customer’s bank) for authorization.
- The issuing bank checks the availability of funds and either approves or declines the transaction.
- Transaction Processing:
- If approved, the payment gateway API processes the transaction, transferring the funds from the customer’s account to the merchant’s account.
- The API sends a confirmation response to the merchant’s application, updating the transaction status.
- Settlement:
- The acquiring bank settles the funds with the merchant, typically within one to a few days, depending on the payment gateway’s policies.
Transaction Flow with Payment Gateway APIs
The credit card transaction flow involves several steps, from the initiation of the payment to the final settlement of funds. Here’s a detailed overview of each step when a payment gateway is involved:
1. Customer Initiates Payment
- Action: The customer selects products or services on the merchant’s website or application and proceeds to checkout.
- Details: The customer enters their credit card information (card number, expiration date, CVV) and other necessary details.
2. Merchant Sends Payment Request
- Action: The merchant’s website or application sends a payment request to the payment gateway API.
- Details: This request includes transaction details such as the amount, currency, and customer’s credit card information.
3. Payment Gateway Tokenizes Data
- Action: The payment gateway API tokenizes the sensitive payment information.
- Details: Tokenization replaces the sensitive card information with a secure token, reducing the risk of data breaches.
4. Authorization
- Action: The payment gateway sends an authorization request to the acquiring bank (merchant’s bank).
- Details: The acquiring bank forwards the request to the card network (e.g., Visa, MasterCard), which then forwards it to the issuing bank (customer’s bank).
5. Issuing Bank Verifies Transaction
- Action: The issuing bank verifies the customer’s account details and checks for sufficient funds.
- Details: The bank performs fraud checks and either approves or declines the transaction.
6. Authorization Response
- Action: The issuing bank sends an authorization response back through the card network to the acquiring bank.
- Details: If approved, the response includes an authorization code; if declined, it includes the reason for the decline.
7. Merchant Receives Authorization Response
- Action: The payment gateway sends the authorization response back to the merchant’s website or application.
- Details: The merchant informs the customer of the transaction status (approved or declined).
8. Capture
- Action: Once the order is ready to be fulfilled, the merchant sends a capture request to the payment gateway API.
- Details: The capture request specifies the amount to be captured (can be the full or a partial amount of the authorization).
9. Funds Transfer
- Action: The payment gateway processes the capture request and transfers the funds from the issuing bank to the acquiring bank.
- Details: The transaction is now considered complete, and the funds are moved into the merchant’s account.
10. Confirmation to Merchant and Customer
- Action: The payment gateway sends a confirmation of the capture to the merchant’s application.
- Details: The merchant updates the transaction status and notifies the customer of the successful payment.
11. Settlement
- Action: The acquiring bank settles the funds with the merchant’s account.
- Details: This process typically occurs in batches and may take a few days, depending on the payment gateway and acquiring bank’s policies.
Security Measures in Payment Gateway APIs
Data encryption secures all data transmitted between the merchant’s application and the payment gateway, preventing interception and misuse. Tokenization replaces sensitive card information with a unique identifier, minimizing the risk of data breaches. Advanced fraud detection algorithms and compliance with industry standards like PCI DSS ensure high security and data protection throughout the payment process.
Data Encryption:
- Ensures that all data transmitted between the merchant’s application and the payment gateway is encrypted, preventing interception and misuse.
Tokenization:
- Replaces sensitive card information with a unique identifier (token), reducing the risk of data breaches.
Fraud Detection:
- Advanced algorithms and machine learning techniques are used to detect and prevent fraudulent transactions.
Compliance:
- Adherence to industry standards such as PCI DSS ensures that the payment gateway API maintains high security and data protection standards.
Example API Calls with Payment Gateway APIs
Payment gateway APIs offer a range of functionalities through various API calls, enabling developers to integrate comprehensive payment processing capabilities into their applications. Here are some of the main API calls and their functionalities:
Create Sale Transaction
Endpoint: POST /v1/transactions
Functionality : This API call initiates a new payment transaction. The merchant’s application sends the transaction details, including the amount, currency, and payment method information (e.g., credit card details), to the payment gateway. The API processes this information, tokenizes sensitive data, and returns a response with the transaction status and a unique transaction ID.
Example Sale Transaction Request
{
"amount": 1000,
"currency": "USD",
"payment_method": {
"type": "card",
"card": {
"number": "4242424242424242",
"exp_month": "12",
"exp_year": "2024",
"cvc": "123"
}
}
}
Example Sales Transaction Response
{
"id": "txn_123456789",
"status": "succeeded",
"amount": 1000,
"currency": "USD"
}
Refund Transaction
Endpoint: POST /v1/transactions/{transaction_id}/refund
Functionality: This API call initiates a refund for a specific transaction. The merchant specifies the transaction ID and the amount to be refunded. The API processes the refund and updates the transaction status accordingly.
Example Refund Transaction Request
{
"amount": 500
}
Example Refund Transaction Response
{
"id": "txn_123456789_refund_1",
"status": "succeeded",
"amount": 500,
"currency": "USD",
"original_transaction_id": "txn_123456789"
}
Store Customer Information Transaction
Endpoint: POST /v1/customers/create_with_payment_method
Functionality: This API call creates a new customer and simultaneously stores their credit card information, returning a combined response with both customer and payment method details.
Example Store Customer Information Transaction Request
{
"customer": {
"name": "John Doe",
"email": "john.doe@example.com"
},
"payment_method": {
"type": "card",
"card": {
"number": "4242424242424242",
"exp_month": "12",
"exp_year": "2024",
"cvc": "123"
}
}
}
Example Store Customer Information Transaction Response
{
"customer": {
"id": "cust_123456789",
"name": "John Doe",
"email": "john.doe@example.com",
"created_at": "2024-06-01T12:00:00Z"
},
"payment_method": {
"id": "pm_987654321",
"type": "card",
"card": {
"last4": "4242",
"exp_month": "12",
"exp_year": "2024"
},
"created_at": "2024-06-01T12:05:00Z"
}
}
