API Documentation Portfolio: Payment Gateway Integration API
1. Overview
This documentation provides a comprehensive guide for integrating with the PayPulse REST API. The API allows merchants to process online transactions, manage customer payment methods, and query transaction statuses securely.
2. Base URL & Authentication
Base URL
All requests should be sent to:
[https://api.paypulse-example.com/v1](https://api.paypulse-example.com/v1)
Authentication
The API uses Bearer Token authentication. Include your API secret key in the HTTP header for all requests:
Authorization: Bearer YOUR_SECRET_API_KEY
Content-Type: application/json
3. Endpoints
A. Create a Payment Charge
HTTP Method: POST
Endpoint: /charges
Description: Creates a new payment transaction.
Request Headers:
Authorization: Bearer sk_test_123456789
Content-Type: application/json
Request Body (JSON):
{
"amount": 2500,
"currency": "USD",
"customer_email": "client@example.com",
"payment_method": "card_token_998877",
"description": "Subscription Fee - October 2026"
}
Successful Response (201 Created):
{
"status": "success",
"transaction_id": "ch_9A8B7C6D",
"amount": 2500,
"currency": "USD",
"state": "completed",
"created_at": "2026-10-22T21:30:00Z"
}
B. Retrieve Transaction Details
HTTP Method: GET
Endpoint: /charges/{transaction_id}
Description: Retrieves the status and details of a specific payment transaction.
Get abdela muhammed’s stories in your inbox
Join Medium for free to get updates from this writer.
Request Example (cURL):
curl -X GET https://api.paypulse-example.com/v1/charges/ch_9A8B7C6D \
-H "Authorization: Bearer sk_test_123456789"
Response (200 OK):
{
"transaction_id": "ch_9A8B7C6D",
"amount": 2500,
"currency": "USD",
"state": "completed",
"customer_email": "client@example.com",
"created_at": "2026-10-22T21:30:00Z"
}
4. Error Handling
The API uses standard HTTP response codes to indicate success or failure:
HTTP Status
Error Code
Description
400
invalid_request
Required parameters are missing or malformed.
401
unauthorized
Invalid or missing API Key.
404
not_found
The requested resource (e.g., transaction ID) does not exist.
500
internal_error
Something went wrong on the server side.
Error Response Example (400 Bad Request):
{
"error": {
"code": "invalid_request",
"message": "Parameter 'amount' must be greater than zero."
}
}
