Paymend API documentation

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12997,
  "currency": "USD",
  "paymentMethod": {
    "type": "CARD"
  },
  "merchantReference": "PAYMENT-12345",
  "goodsType": "MIXED",
  "source": {
    "storeId": "store_abc123",
    "initiatedBy": "MERCHANT"
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "previousFailures": [
    {
      "gateway": "AcquirerX",
      "attemptNumber": 1,
      "responseCode": "05",
      "reason": "Do not honor",
      "timestamp": "2025-11-05T14:22:10Z"
    },
    {
      "gateway": "ProcessorY",
      "attemptNumber": 2,
      "responseCode": "14",
      "reason": "Invalid card number",
      "timestamp": "2025-11-05T14:24:32Z"
    }
  ]
}
'

import requests

url = "http://localhost:8080/api/v1/payments"

payload = {
    "amount": 12997,
    "currency": "USD",
    "paymentMethod": { "type": "CARD" },
    "merchantReference": "PAYMENT-12345",
    "goodsType": "MIXED",
    "source": {
        "storeId": "store_abc123",
        "initiatedBy": "MERCHANT"
    },
    "captureNow": True,
    "descriptor": "MyStore Online",
    "productItems": [
        {
            "id": "PROD-001",
            "name": "Wireless Keyboard",
            "quantity": 2,
            "unitPrice": 4999,
            "goodsType": "PHYSICAL"
        },
        {
            "id": "PROD-002",
            "name": "E-Book Subscription",
            "quantity": 1,
            "unitPrice": 2999,
            "goodsType": "DIGITAL"
        }
    ],
    "shipping": {
        "address": {
            "street": "123 Main Street",
            "city": "San Francisco",
            "country": "US",
            "state": "CA",
            "zip": "94105"
        },
        "firstName": "Jane",
        "lastName": "Smith"
    },
    "previousFailures": [
        {
            "gateway": "AcquirerX",
            "attemptNumber": 1,
            "responseCode": "05",
            "reason": "Do not honor",
            "timestamp": "2025-11-05T14:22:10Z"
        },
        {
            "gateway": "ProcessorY",
            "attemptNumber": 2,
            "responseCode": "14",
            "reason": "Invalid card number",
            "timestamp": "2025-11-05T14:24:32Z"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 12997,
    currency: 'USD',
    paymentMethod: {type: 'CARD'},
    merchantReference: 'PAYMENT-12345',
    goodsType: 'MIXED',
    source: {storeId: 'store_abc123', initiatedBy: 'MERCHANT'},
    captureNow: true,
    descriptor: 'MyStore Online',
    productItems: [
      {
        id: 'PROD-001',
        name: 'Wireless Keyboard',
        quantity: 2,
        unitPrice: 4999,
        goodsType: 'PHYSICAL'
      },
      {
        id: 'PROD-002',
        name: 'E-Book Subscription',
        quantity: 1,
        unitPrice: 2999,
        goodsType: 'DIGITAL'
      }
    ],
    shipping: {
      address: {
        street: '123 Main Street',
        city: 'San Francisco',
        country: 'US',
        state: 'CA',
        zip: '94105'
      },
      firstName: 'Jane',
      lastName: 'Smith'
    },
    previousFailures: [
      {
        gateway: 'AcquirerX',
        attemptNumber: 1,
        responseCode: '05',
        reason: 'Do not honor',
        timestamp: '2025-11-05T14:22:10Z'
      },
      {
        gateway: 'ProcessorY',
        attemptNumber: 2,
        responseCode: '14',
        reason: 'Invalid card number',
        timestamp: '2025-11-05T14:24:32Z'
      }
    ]
  })
};

fetch('http://localhost:8080/api/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/api/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 12997,
    'currency' => 'USD',
    'paymentMethod' => [
        'type' => 'CARD'
    ],
    'merchantReference' => 'PAYMENT-12345',
    'goodsType' => 'MIXED',
    'source' => [
        'storeId' => 'store_abc123',
        'initiatedBy' => 'MERCHANT'
    ],
    'captureNow' => true,
    'descriptor' => 'MyStore Online',
    'productItems' => [
        [
                'id' => 'PROD-001',
                'name' => 'Wireless Keyboard',
                'quantity' => 2,
                'unitPrice' => 4999,
                'goodsType' => 'PHYSICAL'
        ],
        [
                'id' => 'PROD-002',
                'name' => 'E-Book Subscription',
                'quantity' => 1,
                'unitPrice' => 2999,
                'goodsType' => 'DIGITAL'
        ]
    ],
    'shipping' => [
        'address' => [
                'street' => '123 Main Street',
                'city' => 'San Francisco',
                'country' => 'US',
                'state' => 'CA',
                'zip' => '94105'
        ],
        'firstName' => 'Jane',
        'lastName' => 'Smith'
    ],
    'previousFailures' => [
        [
                'gateway' => 'AcquirerX',
                'attemptNumber' => 1,
                'responseCode' => '05',
                'reason' => 'Do not honor',
                'timestamp' => '2025-11-05T14:22:10Z'
        ],
        [
                'gateway' => 'ProcessorY',
                'attemptNumber' => 2,
                'responseCode' => '14',
                'reason' => 'Invalid card number',
                'timestamp' => '2025-11-05T14:24:32Z'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8080/api/v1/payments"

	payload := strings.NewReader("{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/api/v1/payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/payments")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "CAPTURED",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "last4": "1111",
      "cvvPresentDuringAttempt": true,
      "brand": "VISA"
    }
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "goodsType": "MIXED",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "john.doe@example.com",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z",
  "transactions": [
    {
      "id": "SALE_eUfZ9n3BCPJo",
      "type": "SALE",
      "amount": 100,
      "result": "FAILED",
      "failure": {
        "failureCode": "INSUFFICIENT_FUNDS",
        "providerFailureCode": "51"
      },
      "createdAt": "2025-12-15T10:22:10Z"
    },
    {
      "id": "SALE_pU2HnmS8AcpI",
      "type": "SALE",
      "amount": 100,
      "result": "SUCCEEDED",
      "createdAt": "2025-12-16T10:00:00Z"
    },
    {
      "id": "REFN_KmOODVdcacz5",
      "type": "REFUND",
      "amount": 100,
      "result": "SUCCEEDED",
      "createdAt": "2025-12-17T14:14:14Z"
    }
  ],
  "source": {
    "storeId": "store_abc123",
    "initiatedBy": "MERCHANT"
  }
}

{
  "error": "INVALID_REQUEST",
  "message": "The request body is invalid or missing required fields",
  "details": [
    "amount is required",
    "currency must be a valid ISO 4217 code",
    "paymentMethod.card.number is required"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing authorization token",
  "details": [
    "Authorization header is required",
    "Token has expired"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "FAILED",
  "failure": {
    "failureCode": "INSUFFICIENT_FUNDS",
    "providerFailureCode": "51"
  }
}

{
  "error": "BUSINESS_RULE_VIOLATION",
  "message": "Payment request violates business rules",
  "details": [
    "Amount exceeds maximum allowed limit",
    "Currency not supported for this merchant",
    "Card type not accepted"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected server error occurred",
  "details": [
    "Please try again later",
    "Contact support if the issue persists"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "PROVIDER_UNAVAILABLE",
  "message": "Payment processing is temporarily unavailable",
  "details": [
    "Payment provider is experiencing issues",
    "Please retry in a few minutes"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

POST

api

payments

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 12997,
  "currency": "USD",
  "paymentMethod": {
    "type": "CARD"
  },
  "merchantReference": "PAYMENT-12345",
  "goodsType": "MIXED",
  "source": {
    "storeId": "store_abc123",
    "initiatedBy": "MERCHANT"
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "previousFailures": [
    {
      "gateway": "AcquirerX",
      "attemptNumber": 1,
      "responseCode": "05",
      "reason": "Do not honor",
      "timestamp": "2025-11-05T14:22:10Z"
    },
    {
      "gateway": "ProcessorY",
      "attemptNumber": 2,
      "responseCode": "14",
      "reason": "Invalid card number",
      "timestamp": "2025-11-05T14:24:32Z"
    }
  ]
}
'

import requests

url = "http://localhost:8080/api/v1/payments"

payload = {
    "amount": 12997,
    "currency": "USD",
    "paymentMethod": { "type": "CARD" },
    "merchantReference": "PAYMENT-12345",
    "goodsType": "MIXED",
    "source": {
        "storeId": "store_abc123",
        "initiatedBy": "MERCHANT"
    },
    "captureNow": True,
    "descriptor": "MyStore Online",
    "productItems": [
        {
            "id": "PROD-001",
            "name": "Wireless Keyboard",
            "quantity": 2,
            "unitPrice": 4999,
            "goodsType": "PHYSICAL"
        },
        {
            "id": "PROD-002",
            "name": "E-Book Subscription",
            "quantity": 1,
            "unitPrice": 2999,
            "goodsType": "DIGITAL"
        }
    ],
    "shipping": {
        "address": {
            "street": "123 Main Street",
            "city": "San Francisco",
            "country": "US",
            "state": "CA",
            "zip": "94105"
        },
        "firstName": "Jane",
        "lastName": "Smith"
    },
    "previousFailures": [
        {
            "gateway": "AcquirerX",
            "attemptNumber": 1,
            "responseCode": "05",
            "reason": "Do not honor",
            "timestamp": "2025-11-05T14:22:10Z"
        },
        {
            "gateway": "ProcessorY",
            "attemptNumber": 2,
            "responseCode": "14",
            "reason": "Invalid card number",
            "timestamp": "2025-11-05T14:24:32Z"
        }
    ]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 12997,
    currency: 'USD',
    paymentMethod: {type: 'CARD'},
    merchantReference: 'PAYMENT-12345',
    goodsType: 'MIXED',
    source: {storeId: 'store_abc123', initiatedBy: 'MERCHANT'},
    captureNow: true,
    descriptor: 'MyStore Online',
    productItems: [
      {
        id: 'PROD-001',
        name: 'Wireless Keyboard',
        quantity: 2,
        unitPrice: 4999,
        goodsType: 'PHYSICAL'
      },
      {
        id: 'PROD-002',
        name: 'E-Book Subscription',
        quantity: 1,
        unitPrice: 2999,
        goodsType: 'DIGITAL'
      }
    ],
    shipping: {
      address: {
        street: '123 Main Street',
        city: 'San Francisco',
        country: 'US',
        state: 'CA',
        zip: '94105'
      },
      firstName: 'Jane',
      lastName: 'Smith'
    },
    previousFailures: [
      {
        gateway: 'AcquirerX',
        attemptNumber: 1,
        responseCode: '05',
        reason: 'Do not honor',
        timestamp: '2025-11-05T14:22:10Z'
      },
      {
        gateway: 'ProcessorY',
        attemptNumber: 2,
        responseCode: '14',
        reason: 'Invalid card number',
        timestamp: '2025-11-05T14:24:32Z'
      }
    ]
  })
};

fetch('http://localhost:8080/api/v1/payments', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "8080",
  CURLOPT_URL => "http://localhost:8080/api/v1/payments",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 12997,
    'currency' => 'USD',
    'paymentMethod' => [
        'type' => 'CARD'
    ],
    'merchantReference' => 'PAYMENT-12345',
    'goodsType' => 'MIXED',
    'source' => [
        'storeId' => 'store_abc123',
        'initiatedBy' => 'MERCHANT'
    ],
    'captureNow' => true,
    'descriptor' => 'MyStore Online',
    'productItems' => [
        [
                'id' => 'PROD-001',
                'name' => 'Wireless Keyboard',
                'quantity' => 2,
                'unitPrice' => 4999,
                'goodsType' => 'PHYSICAL'
        ],
        [
                'id' => 'PROD-002',
                'name' => 'E-Book Subscription',
                'quantity' => 1,
                'unitPrice' => 2999,
                'goodsType' => 'DIGITAL'
        ]
    ],
    'shipping' => [
        'address' => [
                'street' => '123 Main Street',
                'city' => 'San Francisco',
                'country' => 'US',
                'state' => 'CA',
                'zip' => '94105'
        ],
        'firstName' => 'Jane',
        'lastName' => 'Smith'
    ],
    'previousFailures' => [
        [
                'gateway' => 'AcquirerX',
                'attemptNumber' => 1,
                'responseCode' => '05',
                'reason' => 'Do not honor',
                'timestamp' => '2025-11-05T14:22:10Z'
        ],
        [
                'gateway' => 'ProcessorY',
                'attemptNumber' => 2,
                'responseCode' => '14',
                'reason' => 'Invalid card number',
                'timestamp' => '2025-11-05T14:24:32Z'
        ]
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "http://localhost:8080/api/v1/payments"

	payload := strings.NewReader("{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("http://localhost:8080/api/v1/payments")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/payments")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 12997,\n  \"currency\": \"USD\",\n  \"paymentMethod\": {\n    \"type\": \"CARD\"\n  },\n  \"merchantReference\": \"PAYMENT-12345\",\n  \"goodsType\": \"MIXED\",\n  \"source\": {\n    \"storeId\": \"store_abc123\",\n    \"initiatedBy\": \"MERCHANT\"\n  },\n  \"captureNow\": true,\n  \"descriptor\": \"MyStore Online\",\n  \"productItems\": [\n    {\n      \"id\": \"PROD-001\",\n      \"name\": \"Wireless Keyboard\",\n      \"quantity\": 2,\n      \"unitPrice\": 4999,\n      \"goodsType\": \"PHYSICAL\"\n    },\n    {\n      \"id\": \"PROD-002\",\n      \"name\": \"E-Book Subscription\",\n      \"quantity\": 1,\n      \"unitPrice\": 2999,\n      \"goodsType\": \"DIGITAL\"\n    }\n  ],\n  \"shipping\": {\n    \"address\": {\n      \"street\": \"123 Main Street\",\n      \"city\": \"San Francisco\",\n      \"country\": \"US\",\n      \"state\": \"CA\",\n      \"zip\": \"94105\"\n    },\n    \"firstName\": \"Jane\",\n    \"lastName\": \"Smith\"\n  },\n  \"previousFailures\": [\n    {\n      \"gateway\": \"AcquirerX\",\n      \"attemptNumber\": 1,\n      \"responseCode\": \"05\",\n      \"reason\": \"Do not honor\",\n      \"timestamp\": \"2025-11-05T14:22:10Z\"\n    },\n    {\n      \"gateway\": \"ProcessorY\",\n      \"attemptNumber\": 2,\n      \"responseCode\": \"14\",\n      \"reason\": \"Invalid card number\",\n      \"timestamp\": \"2025-11-05T14:24:32Z\"\n    }\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "CAPTURED",
  "paymentMethod": {
    "type": "CARD",
    "card": {
      "bin": "41111111",
      "holderName": "John Doe",
      "expiryMonth": "12",
      "expiryYear": "2030",
      "last4": "1111",
      "cvvPresentDuringAttempt": true,
      "brand": "VISA"
    }
  },
  "captureNow": true,
  "descriptor": "MyStore Online",
  "goodsType": "MIXED",
  "productItems": [
    {
      "id": "PROD-001",
      "name": "Wireless Keyboard",
      "quantity": 2,
      "unitPrice": 4999,
      "goodsType": "PHYSICAL"
    },
    {
      "id": "PROD-002",
      "name": "E-Book Subscription",
      "quantity": 1,
      "unitPrice": 2999,
      "goodsType": "DIGITAL"
    }
  ],
  "consumer": {
    "firstName": "John",
    "email": "john.doe@example.com",
    "lastName": "Doe",
    "phone": "+1234567890",
    "ip": "192.168.1.1"
  },
  "billing": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    }
  },
  "shipping": {
    "address": {
      "street": "123 Main Street",
      "city": "San Francisco",
      "country": "US",
      "state": "CA",
      "zip": "94105"
    },
    "firstName": "Jane",
    "lastName": "Smith"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z",
  "transactions": [
    {
      "id": "SALE_eUfZ9n3BCPJo",
      "type": "SALE",
      "amount": 100,
      "result": "FAILED",
      "failure": {
        "failureCode": "INSUFFICIENT_FUNDS",
        "providerFailureCode": "51"
      },
      "createdAt": "2025-12-15T10:22:10Z"
    },
    {
      "id": "SALE_pU2HnmS8AcpI",
      "type": "SALE",
      "amount": 100,
      "result": "SUCCEEDED",
      "createdAt": "2025-12-16T10:00:00Z"
    },
    {
      "id": "REFN_KmOODVdcacz5",
      "type": "REFUND",
      "amount": 100,
      "result": "SUCCEEDED",
      "createdAt": "2025-12-17T14:14:14Z"
    }
  ],
  "source": {
    "storeId": "store_abc123",
    "initiatedBy": "MERCHANT"
  }
}

{
  "error": "INVALID_REQUEST",
  "message": "The request body is invalid or missing required fields",
  "details": [
    "amount is required",
    "currency must be a valid ISO 4217 code",
    "paymentMethod.card.number is required"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "UNAUTHORIZED",
  "message": "Invalid or missing authorization token",
  "details": [
    "Authorization header is required",
    "Token has expired"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "paymentId": "pay_1234567890abcdef",
  "merchantReference": "ORDER-12345",
  "amount": 12997,
  "currency": "USD",
  "status": "FAILED",
  "failure": {
    "failureCode": "INSUFFICIENT_FUNDS",
    "providerFailureCode": "51"
  }
}

{
  "error": "BUSINESS_RULE_VIOLATION",
  "message": "Payment request violates business rules",
  "details": [
    "Amount exceeds maximum allowed limit",
    "Currency not supported for this merchant",
    "Card type not accepted"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected server error occurred",
  "details": [
    "Please try again later",
    "Contact support if the issue persists"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "PROVIDER_UNAVAILABLE",
  "message": "Payment processing is temporarily unavailable",
  "details": [
    "Payment provider is experiencing issues",
    "Please retry in a few minutes"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

Authorizations

Authorization

string

header

required

Enter your API token

Headers

User-Agent

string

Body

application/json

amount

integer

required

Payment amount in the smallest currency unit (e.g., cents).

Example:

12997

currency

string

required

Three-letter ISO 4217 currency code (e.g., USD, EUR).

Pattern: ^[A-Z]{3}$

Example:

"USD"

paymentMethod

object

required

The chosen payment method details (e.g., card).

Show child attributes

merchantReference

string

required

Merchant's unique identifier for this payment.

Example:

"PAYMENT-12345"

goodsType

enum<string>

required

Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.

Available options:

PHYSICAL,

DIGITAL,

MIXED

Example:

"MIXED"

source

object

required

Details related to where the payment originated.

Show child attributes

captureNow

boolean

Determines how the payment is processed. Default: false → Authorization only (funds reserved, must capture later). If true → Sale (authorize and capture in one step).

Example:

true

descriptor

string

Text shown on the customer's bank statement (e.g., merchant or product name).

Example:

"MyStore Online"

productItems

object[]

List of product or service items included in this payment.

Show child attributes

Example:

[
  {
    "id": "PROD-001",
    "name": "Wireless Keyboard",
    "quantity": 2,
    "unitPrice": 4999,
    "goodsType": "PHYSICAL"
  },
  {
    "id": "PROD-002",
    "name": "E-Book Subscription",
    "quantity": 1,
    "unitPrice": 2999,
    "goodsType": "DIGITAL"
  }
]

consumer

object

Consumer details such as name, email, phone.

Show child attributes

billing

object

Billing address information.

Show child attributes

shipping

object

Shipping address and recipient details.

Show child attributes

previousFailures

object[]

Array of previous failed payment attempts with other providers.

Show child attributes

Example:

[
  {
    "gateway": "AcquirerX",
    "attemptNumber": 1,
    "responseCode": "05",
    "reason": "Do not honor",
    "timestamp": "2025-11-05T14:22:10Z"
  },
  {
    "gateway": "ProcessorY",
    "attemptNumber": 2,
    "responseCode": "14",
    "reason": "Invalid card number",
    "timestamp": "2025-11-05T14:24:32Z"
  }
]

Response

paymentId

string

Unique identifier for the payment generated by the system.

Maximum string length: 32

Example:

"pay_1234567890abcdef"

merchantReference

string

Reference passed in by the merchant for correlation.

Example:

"ORDER-12345"

amount

integer

Amount processed in the smallest currency unit.

Example:

12997

currency

string

ISO 4217 currency code used in the payment.

Example:

"USD"

status

enum<string>

Current state of the payment.

Available options:

PENDING,

AUTHORIZED,

CAPTURED,

REFUNDED,

VOIDED,

FAILED

Example:

"CAPTURED"

paymentMethod

object

The chosen payment method details (e.g., card). Sensitive fields are masked in responses.

Show child attributes

captureNow

boolean

Determines how the payment is processed. Default: false → Authorization only (funds reserved, must capture later). If true → Sale (authorize and capture in one step).

Example:

true

descriptor

string

Text shown on the customer's bank statement (e.g., merchant or product name).

Example:

"MyStore Online"

goodsType

enum<string>

Type of goods being purchased: PHYSICAL = tangible items, DIGITAL = non-physical items, MIXED = combination of both.

Available options:

PHYSICAL,

DIGITAL,

MIXED

Example:

"MIXED"

productItems

object[]

List of product or service items included in this payment.

Show child attributes

Example:

[
  {
    "id": "PROD-001",
    "name": "Wireless Keyboard",
    "quantity": 2,
    "unitPrice": 4999,
    "goodsType": "PHYSICAL"
  },
  {
    "id": "PROD-002",
    "name": "E-Book Subscription",
    "quantity": 1,
    "unitPrice": 2999,
    "goodsType": "DIGITAL"
  }
]

consumer

object

Consumer details such as name, email, phone.

Show child attributes

billing

object

Billing address information.

Show child attributes

shipping

object

Shipping address and recipient details.

Show child attributes

createdAt

string<date-time>

Timestamp when the payment was created.

Example:

"2024-01-15T10:30:00Z"

updatedAt

string<date-time>

Timestamp when the payment was last updated.

Example:

"2024-01-15T11:00:00Z"

transactions

object[]

Array of transaction attempts made for this payment.

Show child attributes

Example:

[
  {
    "id": "SALE_eUfZ9n3BCPJo",
    "type": "SALE",
    "amount": 100,
    "result": "FAILED",
    "failure": {
      "failureCode": "INSUFFICIENT_FUNDS",
      "providerFailureCode": "51"
    },
    "createdAt": "2025-12-15T10:22:10Z"
  },
  {
    "id": "SALE_pU2HnmS8AcpI",
    "type": "SALE",
    "amount": 100,
    "result": "SUCCEEDED",
    "createdAt": "2025-12-16T10:00:00Z"
  },
  {
    "id": "REFN_KmOODVdcacz5",
    "type": "REFUND",
    "amount": 100,
    "result": "SUCCEEDED",
    "createdAt": "2025-12-17T14:14:14Z"
  }
]

source

object

Details related to where the payment originated.

Show child attributes

Failure Codes Get payment

API documentation

Endpoints

API Objects

Create payment

Authorizations

Headers

Body

Response