Collection API

Environments & authentication

Use sandbox for development and testing. Switch to production only after the integration has been tested and approved. All API requests use HTTPS.

Authenticate every request

Retrieve merchant credentials from the Developer section of your 3ribe dashboard. Include the following headers on collection requests.

apikey: YOUR_API_KEY
apisecretkey: YOUR_API_SECRET_KEY
Content-Type: application/json

Endpoint reference

Append the endpoint path to your environment’s base URL. The first three operations require the merchant headers above.

Payment flow

1. 01Initiate — send the amount, currency, merchant details and exact paymentMethod value. Store the returned transactionReference and your original requestReference.
2. 02Process — for an approved direct card integration, submit billing and card details against the initiated reference. Other payment methods use their approved processing flows.
3. 03Authenticate — follow returned 3DS HTML or authentication redirect instructions. Use issuer processing only when required by that flow.
4. 04Verify — check the final transaction status, update your payment record and fulfil only after confirming successful payment.

Initiate transaction

Create a collection transaction. Send the amount, currency, merchant slug, payment method and transaction purpose. The API returns a transaction reference and a payment URL where applicable.

{
  "amount": 100,
  "requestReference": "TRN66865587",
  "currency": "GBP",
  "slug": "Moduconsults",
  "paymentMethod": "Pay By Bank",
  "transactionPurpose": "Payment",
  "redirectUrl": "https://3ribeadmin.vercel.app",
  "hasPciDss": true
}

Request parameters

{
  "responseStatus": true,
  "responseMessage": "Payment initialised successfully",
  "transactionReference": "TRN18412533288B",
  "paymentUrl": "https://grantspaymentsandboxpay.3ribe.io?name=Moduconsults&currency=GBP&amount=100&narration=Payment&transref=TRN18412533288B&paymentmethod=Pay By Bank&id=39057d635dfc456e9bc204e2e6b8db6f&bankurl=https://sandbox.paybylink.volumepay.io?paymentIntentId=4b5425a6-67f7-4d3a-93e1-00323043ec7c",
  "merchantDescription": "Payment"
}

Response parameters

Continue the transaction

1. 01Store transactionReference and retain requestReference for reconciliation.
2. 02Use paymentUrl for a hosted payment journey. Treat it as an opaque destination: do not construct or modify its query parameters.
3. 03For the approved direct card flow, continue to Process Transaction. Do not create a second transaction simply because the customer has not completed the journey.

Process transaction

Process an initiated transaction when collecting card details directly through the approved card-processing integration. The response may include HTML for 3DS Method authentication.

{
  "amount": 100,
  "transactionReference": "TRN72220445257C",
  "billingEmail": "customer@example.com",
  "billingFirstName": "TEST",
  "billingLastName": "CUSTOMER",
  "billingAddress": "10 Example Street",
  "billingCity": "London",
  "billingState": "London",
  "billingPostalCode": "SW1A 1AA",
  "billingCountry2LetterCode": "GB",
  "cardNumber": "4918190000000002",
  "cardMonth": "12",
  "cardYear": "2033",
  "cardCvv": "123",
  "billingPhoneNumber": "+441234567890",
  "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 Chrome/150.0.0.0 Safari/537.36"
}

Request parameters

The specification lists the following fields and types. Required/optional flags are not supplied; confirm validation rules with 3ribe.

{
  "amount": 100,
  "responseMessage": "Transaction requires authentication",
  "responseStatus": true,
  "transactionReference": "TRN72220445257C",
  "isSettledIntoWallet": false,
  "iFrameHtml": "<!DOCTYPE html>\r\n<html>\r\n<head>\r\n    <meta charset=\"UTF-8\">\r\n</head>\r\n<body>\r\n    <iframe width=\"5000\" height=\"500\" id=\"threeDSMethodIframe\" name=\"threeDSMethodIframe\"></iframe>\r\n    <form id=\"threeDSMethodForm\" name=\"threeDSMethodForm\" enctype=\"application/x-www-form-urlencoded;charset=UTF-8\" style=\"display:none\" method=\"post\" action=\"https://staging.gate.emerchantpay.net/threeds/threeds_method\" target=\"threeDSMethodIframe\">\r\n        <input type=\"hidden\" name=\"unique_id\" value=\"55aee074ab27d1b65fb5e04960fe8153\" />\r\n        <input type=\"hidden\" name=\"signature\" value=\"aa02ab40160c7b4e49cb6020003aa3185857e6a47ff9b072771ea81786d597a37fba83fc1cbc28cda135236ff3276c608c6998b88cdd3a26b25f452af3559013\" />\r\n    </form>\r\n    <script>\r\n        document.getElementById(\"threeDSMethodForm\").submit();\r\n    </script>\r\n</body>\r\n</html>",
  "partiallyApprovedAmount": 0,
  "isPartiallyApproved": false
}

3DS & issuer authentication

3-D Secure authenticates eligible card transactions. A frictionless flow needs no interactive customer action; a challenge may require a one-time password, banking app approval or another issuer-defined action.

Handle the returned authentication instructions

1. 01Inspect the processing response. When iFrameHtml is returned, render the supplied HTML using the approved integration approach.
2. 02The HTML creates an iframe and hidden form, then submits authentication information to the 3DS Method endpoint. Use the returned HTML instead of generating your own form.
3. 03Allow any customer challenge to finish. If the applicable response returns redirectUrl, follow that authentication URL; it is not the merchant’s return URL.
4. 04Continue with issuer processing after the iframe script completes, only when the preceding authentication flow requires it. Then verify the payment outcome.

Process issuer transaction

This operation supports the issuer-processing stage of 3DS and uses the same merchant headers. The exact request and response bodies are not included in the supplied documentation.

PCI DSS configuration

Wallets & Pay By Bank

Apple Pay

Enable Apple Pay in the merchant payment configuration and use an eligible integration. Meet Apple’s domain and security requirements where applicable and use the Apple Pay payment data and flow approved by 3ribe.

1. 01Customer selects Apple Pay; initiate with paymentMethod: "Apple Pay".
2. 02Present the Apple Pay interface and let the customer authorise.
3. 03Submit Apple Pay payment information using the approved 3ribe flow, then verify the final status.

Sandbox: configure an Apple Pay sandbox tester and the appropriate environment. Testing guide: https://developer.apple.com/apple-pay/sandbox-testing/

Google Pay

Enable Google Pay for the merchant and configure the correct environment. Use the payment token returned by Google Pay and submit it through the approved 3ribe processing flow.

1. 01Customer selects Google Pay; initiate with paymentMethod: "Google Pay".
2. 02Google Pay presents available payment instruments. The customer selects one and authorises payment.
3. 03Use the returned payment token in the approved processing flow, then verify final status.

Sandbox: use Google Pay Test Mode and the applicable Test Mode Stub Data Group to generate test payment information.

Pay By Bank

1. 01Customer selects Pay By Bank; initiate with paymentMethod: "Pay By Bank".
2. 02Send the customer to the returned paymentUrl. They select a supported bank, authenticate and authorise the payment.
3. 03Handle the return to the configured merchant URL where applicable. Verify final status before fulfilment.

In the sandbox journey, choose NatWest Sandbox, enter the customer number and requested PIN values, select the Payment account and confirm. These credentials are for sandbox use only.

Verification & redirects

Verify the final transaction after processing and after the customer returns. Retain the initiation reference, use the agreed transaction identifier, inspect paymentStatus and update the corresponding order. Fulfil only after a confirmed successful payment.

{
  "responseStatus": false,
  "message": "Transaction cancelled",
  "data": {
    "paymentStatus": "CANCELLED",
    "transactionReference": "ORDER-20261030-001"
  }
}

Keep the three destinations distinct

Handle successful, failed and cancelled customer journeys. A return redirect or URL query parameter is not authoritative proof of payment; always verify the transaction.

Webhooks & payment notifications

Use the Webhook API to configure and retrieve the merchant receiver URL. Process notifications idempotently to avoid updating the same transaction more than once.

Sandbox test cards

Errors & security

Protect credentials and payment information

1. 01Use HTTPS, keep credentials backend-only and restrict access to payment-processing functions. Never put API credentials or sensitive payment information in logs.
2. 02Use only processing methods approved for your PCI DSS configuration. Do not store cardholder data unless permitted by the applicable PCI DSS requirements.
3. 03Use a unique merchant reference per payment attempt. Implement duplicate-request and duplicate-payment protection; verify uncertain transactions before retrying.
4. 04Validate incoming notifications using the agreed mechanism. Maintain secure audit logs for reconciliation and show customer-friendly errors.

Integration checklist

Outstanding details

The source is not a complete implementation contract for every flow. Resolve these items with 3ribe before building the affected operations or going live.