Getting Started

Making your first payment

This tutorial walks you through the complete process of making your first test payment using Redpin’s sandbox environment.

Prerequisites

Before starting, ensure you have sandbox credentials from our Partner Integrations Team and basic understanding of the payment flow.

Required items:

  • Sandbox credentials from our Partner Integrations Team
  • Your Customer ID on Redpin’s platform

All API requests require OAuth 2.0 Bearer token authentication. See the Authentication guide for complete setup instructions and token management.

Step-by-step payment process

This step is only required if the person sending the funds is NOT the account holder. If you (the account holder) are sending funds from your own account, skip this step and proceed to Step 2.

Submit compliance data for the third-party customer who will be making the payment:

POST
/api/v1/customers/:customer_id/third-parties
1curl -X POST https://api.redpincompany.com/api/v1/customers/020123456789/third-parties \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "client_customer_details": {
6    "client_customer_ref": "SKYLINE-CLIENT-001",
7    "first_name": "Sarah",
8    "last_name": "Johnson",
9    "email": "sarah.johnson@example.com",
10    "mobile_phone": "+14155552671",
11    "country": "USA",
12    "date_of_birth": "1985-03-15",
13    "address": {
14      "address_line": "123 Main St, Apt 4B",
15      "city": "New York",
16      "state": "NY",
17      "post_code": "10001",
18      "country": "USA"
19    },
20    "currency": "USD",
21    "occupation": "Software Engineer",
22    "employer_name": "Google",
23    "income_range": {
24      "currency": "GBP",
25      "min_value": 10000,
26      "max_value": 20000
27    }
28  },
29  "property_details": [
30    {
31      "property_ref": "SKYLINE_HEIGHTS/SKYLINE_TOWER/1001",
32      "unit_number": "1001",
33      "building_name": "Skyline Tower",
34      "project_name": "Skyline Heights Apartments",
35      "property_purchase_amount": {
36        "currency": "USD",
37        "value": 10000
38      },
39      "payment_schedule": [
40        {
41          "payment_date": "2024-01-15",
42          "amount": {
43            "currency": "USD",
44            "value": 5000
45          }
46        },
47        {
48          "payment_date": "2024-06-15",
49          "amount": {
50            "currency": "USD",
51            "value": 5000
52          }
53        }
54      ]
55    },
56    {
57      "property_ref": "SKYLINE_HEIGHTS/SKYLINE_TOWER/1002",
58      "unit_number": "1002",
59      "building_name": "Skyline Tower",
60      "project_name": "Skyline Heights Apartments",
61      "property_purchase_amount": {
62        "currency": "USD",
63        "value": 12000
64      },
65      "payment_schedule": [
66        {
67          "payment_date": "2024-02-15",
68          "amount": {
69            "currency": "USD",
70            "value": 6000
71          }
72        },
73        {
74          "payment_date": "2024-07-15",
75          "amount": {
76            "currency": "USD",
77            "value": 6000
78          }
79        }
80      ]
81    }
82  ]
83}'
Response
1{
2  "client_customer_ref": "SKYLINE-CLIENT-001",
3  "status": "APPROVED"
4}

When to use this step:

  • Property developers collecting payments from buyers
  • Platforms facilitating payments on behalf of their users
  • Any scenario where the funding source is not the account holder

When to skip this step:

  • You are sending funds from your own account
  • Direct account holder transactions

Request a quote for the currency conversion:

Quotes expire after 30 minutes. Save the quote_id for creating the payment in Step 4.

Register the beneficiary who will receive the payment:

POST
/v2/customers/:customer_id/recipients
1curl -X POST https://api.redpincompany.com/v2/customers/cust_123456789/recipients \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "name": "Ahmed Al Mansoori",
6  "type": "Individual",
7  "country_code": "ARE",
8  "customer_own_account": "no",
9  "address": {
10    "address_line": "Office 2101, Jumeirah Bay X2 Tower",
11    "city": "Dubai",
12    "state": "Dubai",
13    "post_code": "000000"
14  },
15  "recipient_bank_details": {
16    "currency": "AED",
17    "iban": "AE070331234567890123456"
18  },
19  "nick_name": "Ahmed UAE",
20  "email": "ahmed.mansoori@example.com",
21  "phone_number": "+971-501234567",
22  "mobile_number": "+971-501234567",
23  "client_reference_id": "recipient-123",
24  "payment_reference": "Invoice#4567"
25}'
Response
1{
2  "client_reference_id": "recipient-123",
3  "recipient_id": "1668758"
4}

Create the payment order with automatic FX conversion:

Important: Set the is_third_party_payment flag based on the same decision from Step 1:

  • is_third_party_payment: true - If you submitted third-party customer data in Step 1
  • is_third_party_payment: false - If you skipped Step 1 (account holder sending own funds)
POST
/v3/customers/:customer_id/payments
1curl -X POST https://api.redpincompany.com/v3/customers/cust_123456789/payments \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "purpose_of_transaction": "PROPERTY_PURCHASE",
6  "amount": {
7    "currency": "GBP",
8    "value": 50000
9  },
10  "recipient_details": [
11    {
12      "amount": {
13        "currency": "GBP",
14        "value": 50000
15      },
16      "recipient_id": "REC-001",
17      "payment_reference": "PROPERTY_PURCHASE_PAYMENT"
18    }
19  ],
20  "quote_id": "548eb44b-5e1b-45fb-86eb-88eb5bcaa781",
21  "property_ref": "PROPERTY-001",
22  "is_third_party_payment": true,
23  "client_customer_ref": "CUST-001"
24}'
Response
1{
2  "payment_id": "PAY-2024-001",
3  "amount": {
4    "currency": "AUD",
5    "value": 50000
6  },
7  "recipient_details": [
8    {
9      "recipient_id": "REC-001",
10      "recipient_name": "John Smith",
11      "amount": {
12        "currency": "GBP",
13        "value": 50000
14      },
15      "payment_reference": "INSTALLMENT1"
16    }
17  ],
18  "status": "AWAITING_FUNDS",
19  "created_datetime": "2024-01-15T10:30:00Z"
20}

Key parameters:

  • is_third_party_payment: Must match whether you completed Step 1
  • client_customer_ref: Required when is_third_party_payment: true
  • quote_id: From Step 2
  • recipient_details: From Step 3

Retrieve the bank details for the customer to send their payment:

GET
/v3/customers/:customer_id/payments/:payment_id/bank-transfer-instructions
1curl -G https://api.redpincompany.com/v3/customers/020123456789/payments/987654321/bank-transfer-instructions \
2     -H "Authorization: Bearer <token>" \
3     -d from_country=GBR
Response
1{
2  "payment_method": "domestic_transfer",
3  "amount": {
4    "currency": "currency",
5    "value": 1.1
6  },
7  "account_details": {
8    "name": "Wattson",
9    "address": "Texas, Texas, Texas, 32323, USA"
10  },
11  "bank_details": {
12    "name": "JP Morgan Chase",
13    "address": "J.P. Morgan Florida 12345",
14    "routing_codes": [
15      {
16        "type": "ROUTING_EFT",
17        "value": "028000024",
18        "label": "EFT routing number"
19      },
20      {
21        "type": "ROUTING_WIRE",
22        "value": "021000021",
23        "label": "Wire routing number"
24      },
25      {
26        "type": "ACCOUNT_NUMBER",
27        "value": "20000023381857",
28        "label": "Account number"
29      },
30      {
31        "type": "ACCOUNT_TYPE",
32        "value": "checking",
33        "label": "Account type"
34      }
35    ]
36  },
37  "payment_reference": {
38    "value": "ABCD123456",
39    "label": "Payment reference",
40    "disclaimer": "Always include this payment reference – it tells us the money has come from you."
41  }
42}

Webhook configuration

Configure webhooks to receive real-time payment status updates:

POST
/v1/webhooks
1curl -X POST https://api.redpincompany.com/v1/webhooks \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "endpoint": "https://yourapp.com/webhooks/redpin",
6  "event_type": "PAYMENT STATUS"
7}'
Response
1{
2  "id": 1
3}

Webhook signatures are included in the svix-signature header for security verification. See Webhooks documentation for signature validation examples.

Testing the payment flow

In sandbox, payments are automatically simulated with instant status updates for testing purposes.

Monitor these status changes during testing:

  1. AWAITING_FUNDS - Payment created, awaiting customer funds
  2. RECEIVED_FUNDS - Funds received, ready for FX conversion
  3. FX_COMPLETED - Currency conversion completed
  4. PAYOUT_INITIATED - Transfer to recipient initiated
  5. PAYMENT_COMPLETED - Payment successfully delivered to recipient

Expected flow:

  • All steps complete without errors
  • Webhooks deliver status updates
  • Final status is PAYMENT_COMPLETED

Quote expiration:

  • Quote expires before conversion creation
  • Regenerate quote and retry

Validation errors:

  • Invalid recipient bank details
  • Incorrect currency codes
  • Missing required fields

Next steps

Error handling

Review error handling patterns and implement robust failure recovery

Production migration

Plan your migration from sandbox to production environment

Integration options

Explore API vs Hosted approaches for your platform

Webhooks setup

Configure production webhooks for real-time notifications