Integration guidelines

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

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

1
curl -X POST https://api.redpincompany.com/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.

You can theme the hosted experience to match your brand by sending a theme payload to the hosted session via postMessage.

Supported Theme Properties:

You can customize the following properties in your theme payload:

• fontFamily - Font family for all text (e.g., "CircularXX, sans-serif", "System")
  • Supported fonts: CircularXX, Helvetica, Roboto, Arial, sans-serif
• baseFontSize - Base font size in pixels (e.g., 16)
• primaryColor - Primary brand color (hex code)
• background - Main background color (hex code)
• textPrimary - Primary text color (hex code)
• textDanger - Error/danger text color (hex code)
• buttonPrimary.bg - Primary button background color (hex code)
• buttonPrimary.text - Primary button text color (hex code)
• borderRadius - Border radius in pixels (e.g., 10, 12)

How Theme Integration Works

Theme integration is a simple, flexible process that works the same way for any frontend application:

• Create Your Theme - Define colors, fonts, and styling that match your brand
• Send Theme to Hosted Page - Use postMessage (web) or JavaScript injection (mobile) to apply your theme when the payment page loads
• Listen for Updates - Handle communication between your app and the hosted payment page for real-time theme mode switches.

Key Benefits for Property Developers:

• Universal Structure: Same theme configuration works for web (iframe) and mobile (WebView) implementations
• Quick Setup: Minimal code changes required to implement theming
• Brand Control: Maintain visual consistency across your entire user journey

Implementation Elements:

Theme Configuration: Your theme configuration uses the same structure regardless of platform:

1
const theme = {
2
  fontFamily: "CircularXX, system-ui, sans-serif",
3
  baseFontSize: 16,
4
  primaryColor: "#0D6EFD",
5
  background: "#FFFFFF",
6
  textPrimary: "#111827",
7
  textDanger: "#EF4444",
8
  buttonPrimary: {
9
    bg: "#0D6EFD",
10
    text: "#FFFFFF"
11
  },
12
  borderRadius: 8
13
};

Message Communication: Your app communicates with the hosted page using the same message format:

1
// Send theme to hosted page
2
{ type: "SET_THEME", payload: theme }
3
4
// Listen for hosted page readiness
5
{ type: "HOSTED_READY" }

Dynamic Theme Generation: Create themes based on user preferences or system settings:

1
const getDynamicTheme = (userPreferences: any, systemTheme: 'light' | 'dark') => {
2
  return {
3
    fontFamily: userPreferences.fontFamily || "System",
4
    baseFontSize: userPreferences.fontSize || 16,
5
    primaryColor: userPreferences.brandColor || "#FF5A1F",
6
    background: systemTheme === 'dark' ? "#0B0F14" : "#FFFFFF",
7
    textPrimary: systemTheme === 'dark' ? "#F9FAFB" : "#1F2937",
8
    textDanger: "#EF4444",
9
    buttonPrimary: {
10
      bg: userPreferences.brandColor || "#FF5A1F",
11
      text: "#FFFFFF"
12
    },
13
    borderRadius: userPreferences.borderRadius || 12
14
  };
15
};

Platform-Specific Implementation

Choose your platform below to see the specific implementation details:

1
import React, { useEffect, useRef, useState } from "react";
2
3
const HOSTED_ORIGIN = "https://hosted.redpin.example"; // Replace with actual origin
4
5
export function HostedCheckoutWithTheme({ sessionUrl }: { sessionUrl: string }) {
6
  const iframeRef = useRef<HTMLIFrameElement | null>(null);
7
  const [isReady, setIsReady] = useState(false);
8
9
  // Listen for hosted page readiness
10
  useEffect(() => {
11
    function handleMessage(event: MessageEvent) {
12
      if (event.origin !== HOSTED_ORIGIN) return;
13
      if (event.data?.type === "HOSTED_READY") {
14
        setIsReady(true);
15
      }
16
    }
17
    window.addEventListener("message", handleMessage);
18
    return () => window.removeEventListener("message", handleMessage);
19
  }, []);
20
21
  // Send theme when ready
22
  useEffect(() => {
23
    if (!isReady || !iframeRef.current) return;
24
    iframeRef.current.contentWindow?.postMessage(
25
      { type: "SET_THEME", payload: theme },
26
      HOSTED_ORIGIN
27
    );
28
  }, [isReady]);
29
30
  return (
31
    <iframe
32
      ref={iframeRef}
33
      src={sessionUrl}
34
      style={{ width: "100%", height: "720px", border: 0 }}
35
      title="Redpin Hosted Session"
36
    />
37
  );
38
}

Best Practices:

1. Performance: Send theme payload when the hosted page loads and when theme changes occur
2. Fallbacks: Provide fallback values for required theme properties
3. Validation: Validate theme payload structure before sending
4. Testing: Test theme integration in both light and dark modes
5. Accessibility: Ensure theme colors maintain sufficient contrast ratios

Important Notes:

• Fallback Theme: If no theme is provided, the hosted page will use a default theme to ensure consistent appearance
• Theme Updates: You can send updated themes when user preferences change (e.g., switching between light/dark mode)

Implement callback URLs to handle successful and failed payment scenarios.

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

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:

Retrieve customer details:

Webhook registration:

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

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

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

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

Quote request:

Recipient registration: Register payment recipients with their banking details:

1
curl -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:

1
curl -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
  "is_third_party_payment": true,
22
  "client_customer_ref": "CUST-001",
23
  "property_ref": "PROPERTY-001"
24
}'

Retrieve transfer instructions: Obtain bank details for customer payments:

1
curl -G https://api.redpincompany.com/v3/customers/020123456789/payments/987654321/bank-transfer-instructions \
2
     -H "Authorization: Bearer <token>" \
3
     -d from_country=GBR

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
}

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.

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

For complete environment details, see the Environments guide.