> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.redpincompany.com/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.redpincompany.com/_mcp/server. # List Payments GET https://sandbox.currenciesdirect.com/v3/customers/{customer_id}/payments Retrieve a paginated list of all payments for a given customer. **Authentication:** [Bearer token required](/api-guide/getting-started/authentication#oauth-20-authentication) Reference: https://docs.redpincompany.com/api-reference/customers/api-integration/payments/list-payments ## Authentication - `Authorization` header (bearer token, required) — OAuth 2.0 Bearer token authentication. This API uses OAuth 2.0 Client Credentials flow. Please refer to the [Authentication](/api-guide/getting-started/authentication#oauth-20-authentication) section for detailed information on how to obtain and use your OAuth credentials. ## Servers - `https://sandbox.currenciesdirect.com` (Sandbox, default) - `https://api.redpincompany.com` (Production) ## Request ### Path parameters - `customer_id` (string, required) — Unique identifier for the customer whose payments are being retrieved. ### Query parameters - `page` (integer, optional) — Page number for pagination. Default is 1 - `limit` (integer, optional) — Number of items per page. Default is 20, max is 100 ## Response ### 200 Successful response with paginated list of payments - `meta_data` (PaginatedPaymentsResponseMetaData, required) - `payments` (list of PaymentDetails, required) ## Errors ### 400 Bad Request Error Bad request - missing or invalid parameters - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ### 500 Internal Server Error Internal server error - `code` (string, required) - `description` (string, required) — Human-readable error description - `type` (enum, optional) — Category or type of the error. - `VALIDATION_ERROR`: Error due to invalid input data or format - `AUTHORIZATION_ERROR`: Error related to insufficient permissions - `SYSTEM_ERROR`: Internal system or server errors - `RESOURCE_ERROR`: Error related to resource availability - `BUSINESS_ERROR`: Error related to business logic violations - `DATA_ERROR`: Error related to data inconsistencies or duplication - Allowed values: `VALIDATION_ERROR`, `AUTHORIZATION_ERROR`, `SYSTEM_ERROR`, `RESOURCE_ERROR`, `BUSINESS_ERROR`, `DATA_ERROR` - `field` (string, optional) - `details` (map from string to any, optional) — Additional details about the error - `timestamp` (datetime, optional) ## Types ### PaginatedPaymentsResponseMetaData - `next_page` (string, required, nullable) — URL to fetch the next page of results, or null if there are no more pages. - `total_records` (integer, required) — Total number of records available. - `total_pages` (integer, required) — Total number of pages available. ### PaymentDetails - `payment_id` (string, required) — Unique identifier assigned by the API when the payment is created. - `instruction_number` (string, required) — Instruction number assigned by the API when the payment is created. - `status` (enum, required) — Current status of the payment. Refer to the [Payment Status Events](/api-reference/webhooks/payments/webhook-payment-status-updated) section for more details about the statuses. - Allowed values: `AWAITING_FUNDS`, `RECEIVED_FUNDS`, `FX_COMPLETED`, `PAYOUT_INITIATED`, `PAYOUT_CREDITED`, `BOUNCED_BACK`, `PAYMENT_COMPLETED`, `PROCESSING`, `CANCELLED` - `payouts` (list of PayoutRecipient, required) - `client_reference_id` (string, optional) — Client-provided reference ID for the payment while creating the payment. - `fx_conversion` (FxConversion, optional) — FX conversion details. **Important:** This field is only present when currency conversion was performed (i.e., when `quote_id` was provided in the payment request). **Not present for same-currency payments** (when source and destination currencies are the same and no `quote_id` was provided). ### PayoutRecipient - `amount` (Amount, required) - `recipient_details` (RecipientDetails, required) — Recipient details are used to identify the recipient of the payment. The recipient_id is a unique identifier of the recipient. The payment_reference is used to identify the payment in the recipient's bank. - `status` (enum, required) — Status of the payment to the recipient. This is the status of the payment to the recipient. **Allowed values:** | Status | Description | |-------------|-------------| | NOT_STARTED | The payment process for this recipient has not begun yet. No action has been taken to initiate the transfer. | | INITIATED | The payment to the recipient has been started, but the funds have not yet been credited to the recipient's account. This typically means the payment is in progress or is being processed by the bank or payment provider. | | COMPLETED | The payment to the recipient has been successfully completed and the funds have been credited to the recipient's account. | | BOUNCED_BACK | The payment to the recipient failed and the funds were returned (bounced back) to Redpin. This can happen due to issues like invalid account details, closed accounts, or other banking errors. | | FAILED | The payment to the recipient could not be completed due to an error or issue (other than a bounce back). This is a general failure status indicating the payment did not succeed. | | CANCELLED | The payment to the recipient was cancelled before it could be completed. This could be due to a user action, a system rule, or a compliance reason. | - Allowed values: `NOT_STARTED`, `INITIATED`, `COMPLETED`, `BOUNCED_BACK`, `FAILED`, `CANCELLED` - `payment_date` (date, required) — Date (in ISO 8601 format (YYYY-MM-DD)) on which the payment will be credited to the recipient. ### FxConversion - `selling_amount` (Amount, required) — Amount being sold. - `buying_amount` (Amount, required) — Amount being bought. - `agreed_rate` (double, required) — Agreed FX conversion rate. - `booking_datetime` (datetime, required) — Date and time (in ISO 8601 format (YYYY-MM-DDTHH:MM:SSZ)) when the FX conversion was booked. - `value_date` (date, required) — The date (in ISO 8601 format (YYYY-MM-DD)) on which the FX conversion will be executed. - `status` (enum, required) — Status of the FX conversion. **Allowed values:** | Status | Description | |--------|-------------| | OPEN | The FX conversion is active and available for use. The agreed FX rate and conversion details are still valid, and the conversion can be used to process payments or settlements. | | CLOSED | The FX conversion has been fully settled or closed. The conversion is no longer available for use—either the funds have been exchanged and settled. | - Allowed values: `OPEN`, `CLOSED` ### Amount - `currency` (string, required) — Three-letter ISO 4217 currency code. - `value` (double, required) — Amount of the payment with 2 decimal precision. ### RecipientDetails Recipient details are used to identify the recipient of the payment. The recipient_id is a unique identifier of the recipient. The payment_reference is used to identify the payment in the recipient's bank. - `recipient_id` (string, required) — Unique identifier of the recipient. - `payment_reference` (string, required) — This reference is used to identify the payment in the recipient's bank. ## Examples ### Payments with FX Conversion **Response** ```json { "meta_data": { "next_page": "/v3/customers/cust_123456789/payments?page=2&limit=5", "total_records": 38, "total_pages": 8 }, "payments": [ { "payment_id": "5636191", "instruction_number": "cust_123456789-000000009", "status": "AWAITING_FUNDS", "payouts": [ { "amount": { "currency": "AED", "value": 107.56 }, "recipient_details": { "recipient_id": "rec_123456789", "payment_reference": "payment to Mashreq account1" }, "status": "NOT_STARTED", "payment_date": "2025-07-10" }, { "amount": { "currency": "AED", "value": 100 }, "recipient_details": { "recipient_id": "rec_987654321", "payment_reference": "payment to Mashreq account2" }, "status": "NOT_STARTED", "payment_date": "2025-07-10" } ], "client_reference_id": "c2860379-c845-4f4e-9d2e-5b058e9114b9", "fx_conversion": { "selling_amount": { "currency": "GBP", "value": 43.24 }, "buying_amount": { "currency": "AED", "value": 207.56 }, "agreed_rate": 4.8794, "booking_datetime": "2025-07-07T13:02:46Z", "value_date": "2025-07-09", "status": "OPEN" } } ] } ``` **SDK Code** ```python Payments with FX Conversion import requests url = "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments" querystring = {"page":"1","limit":"20"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Payments with FX Conversion const url = 'https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Payments with FX Conversion package main import ( "fmt" "net/http" "io" ) func main() { url := "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Payments with FX Conversion require 'uri' require 'net/http' url = URI("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Payments with FX Conversion import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20") .header("Authorization", "Bearer ") .asString(); ``` ```php Payments with FX Conversion request('GET', 'https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Payments with FX Conversion using RestSharp; var client = new RestClient("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Payments with FX Conversion import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ``` ### Same Currency Payments (No FX Conversion) **Response** ```json { "meta_data": { "next_page": "/v3/customers/cust_123456789/payments?page=2&limit=5", "total_records": 38, "total_pages": 8 }, "payments": [ { "payment_id": "3925407", "instruction_number": "0202000010600852-000000672", "status": "PROCESSING", "payouts": [ { "amount": { "currency": "AED", "value": 10 }, "recipient_details": { "recipient_id": "1212774", "payment_reference": "payment-ref-client_ref_545dda27-0" }, "status": "NOT_STARTED", "payment_date": "2025-12-26" } ] } ] } ``` **SDK Code** ```python Same Currency Payments (No FX Conversion) import requests url = "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments" querystring = {"page":"1","limit":"20"} headers = {"Authorization": "Bearer "} response = requests.get(url, headers=headers, params=querystring) print(response.json()) ``` ```javascript Same Currency Payments (No FX Conversion) const url = 'https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20'; const options = {method: 'GET', headers: {Authorization: 'Bearer '}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go Same Currency Payments (No FX Conversion) package main import ( "fmt" "net/http" "io" ) func main() { url := "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby Same Currency Payments (No FX Conversion) require 'uri' require 'net/http' url = URI("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java Same Currency Payments (No FX Conversion) import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20") .header("Authorization", "Bearer ") .asString(); ``` ```php Same Currency Payments (No FX Conversion) request('GET', 'https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```csharp Same Currency Payments (No FX Conversion) using RestSharp; var client = new RestClient("https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20"); var request = new RestRequest(Method.GET); request.AddHeader("Authorization", "Bearer "); IRestResponse response = client.Execute(request); ``` ```swift Same Currency Payments (No FX Conversion) import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://sandbox.currenciesdirect.com/v3/customers/cust_123456789/payments?page=1&limit=20")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```