Paymend API documentation

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments/{paymentId}/capture \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "captureAmount": 12997
}
'

import requests

url = "http://localhost:8080/api/v1/payments/{paymentId}/capture"

payload = { "captureAmount": 12997 }
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({captureAmount: 12997})
};

fetch('http://localhost:8080/api/v1/payments/{paymentId}/capture', 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/{paymentId}/capture",
  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([
    'captureAmount' => 12997
  ]),
  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/{paymentId}/capture"

	payload := strings.NewReader("{\n  \"captureAmount\": 12997\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/{paymentId}/capture")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"captureAmount\": 12997\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/payments/{paymentId}/capture")

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  \"captureAmount\": 12997\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",
      "cvvPresentDuringAttempt": true,
      "expiryMonth": "12",
      "expiryYear": "2030",
      "brand": "VISA"
    }
  },
  "captureNow": false,
  "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",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "shipping": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

{
  "error": "INVALID_REQUEST",
  "message": "The request body is invalid or paymentId format is invalid",
  "details": [
    "paymentId must be a valid string",
    "captureAmount must be a positive integer",
    "captureAmount must be a valid number"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

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

{
  "error": "PAYMENT_NOT_FOUND",
  "message": "Payment not found",
  "details": [
    "No payment found with the specified paymentId"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "CAPTURE_NOT_ALLOWED",
  "message": "Capture cannot be processed",
  "details": [
    "Payment has not been authorized",
    "Capture amount exceeds authorized amount",
    "Payment has already been captured"
  ],
  "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 capturing is temporarily unavailable",
  "details": [
    "Payment provider is experiencing issues",
    "Please retry in a few minutes"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

POST

api

payments

{paymentId}

capture

cURL

curl --request POST \
  --url http://localhost:8080/api/v1/payments/{paymentId}/capture \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "captureAmount": 12997
}
'

import requests

url = "http://localhost:8080/api/v1/payments/{paymentId}/capture"

payload = { "captureAmount": 12997 }
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({captureAmount: 12997})
};

fetch('http://localhost:8080/api/v1/payments/{paymentId}/capture', 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/{paymentId}/capture",
  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([
    'captureAmount' => 12997
  ]),
  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/{paymentId}/capture"

	payload := strings.NewReader("{\n  \"captureAmount\": 12997\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/{paymentId}/capture")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"captureAmount\": 12997\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("http://localhost:8080/api/v1/payments/{paymentId}/capture")

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  \"captureAmount\": 12997\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",
      "cvvPresentDuringAttempt": true,
      "expiryMonth": "12",
      "expiryYear": "2030",
      "brand": "VISA"
    }
  },
  "captureNow": false,
  "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",
    "lastName": "Doe",
    "email": "john.doe@example.com"
  },
  "billing": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "shipping": {
    "firstName": "John",
    "lastName": "Doe",
    "address": {
      "line1": "123 Main St",
      "city": "New York",
      "state": "NY",
      "postalCode": "10001",
      "country": "US"
    }
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "updatedAt": "2024-01-15T11:00:00Z"
}

{
  "error": "INVALID_REQUEST",
  "message": "The request body is invalid or paymentId format is invalid",
  "details": [
    "paymentId must be a valid string",
    "captureAmount must be a positive integer",
    "captureAmount must be a valid number"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

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

{
  "error": "PAYMENT_NOT_FOUND",
  "message": "Payment not found",
  "details": [
    "No payment found with the specified paymentId"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

{
  "error": "CAPTURE_NOT_ALLOWED",
  "message": "Capture cannot be processed",
  "details": [
    "Payment has not been authorized",
    "Capture amount exceeds authorized amount",
    "Payment has already been captured"
  ],
  "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 capturing is temporarily unavailable",
  "details": [
    "Payment provider is experiencing issues",
    "Please retry in a few minutes"
  ],
  "timestamp": "2024-01-15T10:30:00Z"
}

The capture endpoint has been created with the standard structure:

Title: “Capture payment”
OpenAPI reference: POST /api/v1/payments/{paymentId}/capture

This follows the same pattern as your other endpoints (refund, void) and will integrate with your OpenAPI specification. The endpoint allows capturing a previously authorized payment to transfer the funds to the merchant’s account.

Authorizations

Authorization

string

header

required

Enter your API token

Path Parameters

paymentId

string

required

Maximum string length: 32

Body

application/json

Only required when performing a partial capture. For a full capture, this object can be omitted.

captureAmount

integer

Amount to capture in the smallest currency unit (must be ≤ the originally authorized amount).

Required range: x >= 1

Example:

12997

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

Get payment Refund payment

API documentation

Endpoints

API Objects

Capture payment

Authorizations

Path Parameters

Body

Response