Partners

Integration guidelines

This guide outlines integration approaches for property developers and platforms enabling international property payments through Redpin’s APIs.

Common use cases

This guide is designed for property developers, real estate platforms, and fintech companies facilitating cross-border property transactions.

Integration approaches

Redpin offers two distinct integration methods. The following comparison helps property developers select the optimal approach:

AspectHosted SolutionAPI Integration
Development Effort (for Property Developers)Minimal - Pre-built KYC and payment workflowsHigher - Custom implementation of all user flows
Time to MarketFaster with reduced development overheadLonger implementation timeline due to custom development
UI/UX ControlBasic theming options available

Advanced theming possible to align with brand requirements		Full control of UI/UX (to the Property Developers)
Technical IntegrationMinimal Backend and Frontend development requiredFull API suite integration with custom Frontend development
Maintenance OverheadLower - Platform updates handled automaticallyHigher - Full ownership of implementation
Real time updatesWebhook integration for payment status updatesWebhook integration for payment status updates

Decision framework

Choose Hosted Solution

When to choose:

  • Fast time to market is priority
  • Limited development resources available
  • Standard payment flows meet requirements
  • Minimal ongoing maintenance preferred
Choose API Integration

When to choose:

  • Custom user experience requirements
  • Existing payment workflows to integrate
  • Full control over customer journey needed
  • Advanced customization and branding required

Hosted integration workflow

The hosted approach simplifies implementation by redirecting customers to Redpin’s hosted payment interface.

Submit compliance data for the 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}'

Create a payment session with complete transaction details, including client_customer_ref and property_ref:

POST
/api/v1/customers/:customer_id/sessions
1curl -X POST https://api.redpincompany.com/api/v1/customers/customer_123/sessions \
2     -H "Authorization: Bearer <token>" \
3     -H "Content-Type: application/json" \
4     -d '{
5  "client_customer_ref": "CUST-1001-TXN",
6  "property_ref": "PROPERTY-001",
7  "payment_details": {
8    "type": "expression of interest",
9    "amount": {
10      "currency": "AED",
11      "value": 5000.5
12    },
13    "due_date": "2025-08-15",
14    "recipient_details": [
15      {
16        "amount": {
17          "currency": "AED",
18          "value": 3000.25
19        },
20        "recipient": {
21          "name": "John Doe",
22          "type": "Individual",
23          "payment_reference": "RentAug",
24          "customer_own_account": "no",
25          "address": {
26            "address_line": "51 Moorgate",
27            "city": "Dubai",
28            "state": "Dubai",
29            "country": "ARE",
30            "post_code": "123456"
31          },
32          "recipient_bank_details": {
33            "currency": "AED",
34            "iban": "AE070331234567890123456"
35          }
36        }
37      },
38      {
39        "amount": {
40          "currency": "AED",
41          "value": 2000.25
42        },
43        "recipient": {
44          "name": "Jane Smith",
45          "type": "Corporate",
46          "payment_reference": "payment_reference",
47          "customer_own_account": "yes",
48          "address": {
49            "address_line": "221B Baker Street",
50            "city": "Dubai",
51            "state": "Dubai",
52            "country": "ARE",
53            "post_code": "508206"
54          },
55          "recipient_bank_details": {
56            "currency": "AED",
57            "iban": "GB29NWBK60161331926819"
58          }
59        }
60      }
61    ]
62  },
63  "allowed_origins": [
64    "https://app.example.com"
65  ],
66  "callbacks": [
67    "https://webhook.example.com/redpin/session-update"
68  ]
69}'

The session creation response provides options for customer interaction:

  • Web applications: Redirect customers to the returned session URL
  • Embedded iframe: Embed the session URL within your application for integrated experiences
  • Native mobile apps: Open the URL inside an “out of process” WebView, such as ASWebAuthenticationSession in iOS or Android Custom Tab, making the process feel seamless within your application

Customers complete their payment journey within Redpin’s hosted environment, including any required verification steps.

Implement callback URLs to handle successful and failed payment scenarios.

Monitor session expiration times and create new sessions as needed for incomplete payments.

API integration workflow

The following workflow demonstrates complete payment lifecycle management through direct API calls.

Before initiating any payment flow, determine if Redpin should be presented as a payment option.

Display Redpin as the recommended payment method when:

  • User needs to send cross-border multi-currency transfers, and
  • User’s preferred currency is supported by Redpin, and
  • User resides in a country supported by Redpin

Submit compliance data: Submit compliance data for the 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}'

Retrieve customer details:

GET
/api/v1/customers/:customer_id/third-parties/:client_customer_ref
1curl https://api.redpincompany.com/api/v1/customers/020123456789/third-parties/SKYLINE-CLIENT-001 \
2     -H "Authorization: Bearer <token>"

Webhook registration:

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}'

If customer verification passes, continue with the payment flow. If additional verification is required, handle it before proceeding.

Check customer status: Monitor the customer status to determine if you can proceed with payment creation:

GET
/api/v1/customers/:customer_id/third-parties/:client_customer_ref
1curl https://api.redpincompany.com/api/v1/customers/020123456789/third-parties/SKYLINE-CLIENT-001 \
2     -H "Authorization: Bearer <token>"

If verification is complete:

  • Customer status is “success”
  • Continue to quote generation (Step 4)

If additional verification needed:

  • Customer status is “pending” or “failure”
  • Webhook will provide required documents
  • Handle document collection in your UI
  • Monitor status until customer verification succeeds

Quotes typically expire after 30 minutes, so ensure timely customer decision-making.

Currency selection: Allow customers to select their source currency, destination currency, amount, and BUY/SELL operation.

Quote request:

The system returns a quoted amount, quote_id, and expiry time. Monitor quote expiration and regenerate as needed.

Recipient registration: Register payment recipients with their banking details:

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}'

Payment creation: Create payments linking recipients to conversions:

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}'

Retrieve transfer instructions: Obtain bank details for customer payments:

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

Display the returned bank details to customers for wire transfer execution.

Real-time webhook notifications ensure customers stay informed throughout the payment process.

Webhook notifications: Receive real-time updates on conversion and payment status changes for customer service and reconciliation purposes.

Payment status examples:

Awaiting funds:

1{
2  "event_id": "evt_12345678",
3  "payment_id": "87654321",
4  "status": "AWAITING_FUNDS",
5  "customer_id": "cust_12345678",
6  "client_customer_ref": "your_internal_ref",
7  "data": {},
8  "event_timestamp": "2024-01-15T10:30:00Z"
9}

Payment completed:

1{
2  "event_id": "evt_12345679",
3  "payment_id": "87654321",
4  "status": "PAYMENT_COMPLETED",
5  "customer_id": "cust_12345678",
6  "client_customer_ref": "your_internal_ref",
7  "data": {
8    "amount": {
9      "currency": "AED",
10      "value": 20000.58
11    },
12    "recipient_id": "rec_12345678"
13  },
14  "event_timestamp": "2024-01-15T11:45:00Z"
15}

Implementation considerations

Both integration approaches require OAuth 2.0 authentication using Client Credentials flow.

Reference the Authentication documentation for implementation details.

Implement webhook endpoints to receive real-time status updates for:

  • Customer verification status changes
  • Payment status transitions
  • Conversion execution confirmations

Implement comprehensive error handling for:

  • Quote expiration scenarios
  • Customer verification failures
  • Payment processing delays
  • Session timeout events

See the Error handling guide for detailed implementation.

Partners must ensure regulatory compliance for cross-border payment facilitation.

Required implementations:

  • Display of Redpin’s Terms and Conditions
  • Customer consent collection for data sharing
  • Fraud prevention message presentation based on customer jurisdiction
  • Regulatory compliance for cross-border payment facilitation

Utilize Redpin’s sandbox environment for comprehensive integration testing before production deployment.

For complete environment details, see the Environments guide.

Support and resources

Technical support
  • API documentation: Complete endpoint specifications available in the API Reference section
  • Integration support: Contact the Partner Integrations Team
  • Webhook testing: Use sandbox webhooks for development validation
Getting started