Crown Agents Bank APIs

Powered by Segovia

Segovia was acquired by Crown Agents Bank Ltd in 2019 and is a US registered technology arm of the company. For more information about the acquisition of Segovia please click here

CAB's payments gateway is powered by Segovia's technology, and still uses Segovia URLs, so don't be surprised if you see the Segovia name here and there!

Introduction

Crown Agents Bank (CAB)'s objective is to make payments in emerging markets faster, more transparent, more reliable, and more secure. CAB takes the pain out of managing payments in order to allow companies to focus on running their core business. We provide a single point of contact from a technical and customer service standpoint and aim to deliver a world class product on both fronts.

CAB’s payment gateway offers a unified API to execute bulk payments through multiple payment providers (banks and mobile money) in a wide range of countries in emerging and developed markets.

The API is language- and platform-independent. Requests are sent using HTTPS requests, and JSON is the data format for both input and responses. Responses may be sent asynchronously using HTTPS requests from the payment gateway to the client or via polling from the client to the gateway. Transactions are sent in batches to efficiently support bulk-payment operations, but single-transaction batches are supported for use by clients that don’t need bulk payments.

Getting Started

Integrating with CAB's payment gateway is a straightforward process.

Decide on a client configuration for your development environment(s). See the next section. Your CAB technical contact will help you with this.
Generate a pair of request signing keys and upload the public key to the payment gateway's key management interface. See the Request Signatures page for details.
Implement the integration in your code, using the API reference as a guide. As part of this, you'll need to implement request signing. There is example code for that on the Request Signatures page, in Java, Python, and PHP.
Test the integration using the test payment provider to verify your implementation.
Test the integration using real payment providers to confirm that payments are transmitted as expected.
Decide on a client configuration for your production environment.
Deploy your integration to production.
Test the integration using the test payment provider to confirm the production configuration.

The rest of this guide contains more detail about various elements of the process.

Client Configuration

Each payment gateway client has a number of configuration settings. These will be set by a CAB administrator during the account creation process. It's worth noting that from the payment gateway's point of view, a "client" is an identity, not a specific piece of software.

Client ID

A textual unique identifier for this client, analogous to a username. The client ID will typically be assigned by CAB; typically you'll get one client ID for developer use (multiple developers can use the same ID) and another for production use.

Callback URL

If configured, the payment gateway will always send callback requests to this client and will send them to the configured URL. In that case, it's impossible to specify an alternate callback URL in API requests. Configuring the client with a callback URL is recommended for production environments since it prevents transactions from being processed without the client being informed.

For environments that can't accept callbacks (e.g., development systems) this setting will not be present, and the caller will have to poll for the status of transactions.

Request Signing

Each API request, and each callback request from the gateway, includes a signature that's generated using an ECDSA keypair.

During account setup, you generate a keypair, and you upload the public key to CAB's payment platform using the key management interface. CAB never sees your private key, which you use to sign your requests to the payment gateway. The Request Signatures page has instructions for generating a keypair.

Callback requests are signed using CAB's private key, and you should verify the signature using CAB's public key.

Keys are required for all clients, whether production or development/test. Keys must be at least 256 bits in length.

JSON Format

The JSON object format for each API request is described in the API reference documentation.

Example Input

A batch of three payments to three payment providers:

{
  "requestId": "769b870d-5031-4121-98f1-b86b4985037b",
  "batchReference": "test-batch-12345",
  "transactions": [
    {
      "transactionId": "d7722446-b568-4d52-9d4a-c9943b8f17f2",
      "provider": "mtn-rwanda",
      "currency": "RWF",
      "recipientAccountId": "250123456789",
      "name": "Mathias Ntawulikura",
      "amount": 235
    },
    {
      "transactionId": "2737d553-9c76-4207-80a5-fe5e1cec56a1",
      "provider": "safaricom-kenya",
      "currency": "KES",
      "recipientAccountId": "254123456789",
      "amount": 15,
      "name": "Jemima Sumgong"
    },
    {
      "transactionId": "8d92ee08-2ca3-45f7-b69e5e3c224de246",
      "provider": "paga-nigeria",
      "currency": "NGN",
      "recipientAccountId": "234123456789",
      "amount": 30,
      "name": "Olanna Ozobia"
    }
  ]
}

Testing

Test Payment Provider

In addition to live payment providers, the gateway has a payment provider called test that may be used for testing. No money is ever transmitted by the test provider. Relatedly, payments through the test provider are not associated with any client wallets.

Transactions in a request may not mix payments sent to the test provider with other, non-test providers. Requests that contain a mixture of payments to the test provider and other providers will be rejected with code 400.

By default, the test provider will allow all transactions to succeed. However, to support testing error handling in client code, you can pass some special recipientAccountId values. These cause transactions to be delayed or to fail with various status codes, as documented in the API reference section.

recipientAccountId	Status	Description
`12125550000`	420	Recipient account not found.
`12125550001`	370	Recipient account is locked.
`12125550002`	399	Provider rejected the transaction but didn't provide further details about the reason.
`12125550003`	342	Recipient wallet is full.
`12125550014`	371	Recipient is not registered for mobile money.
`12125551000`	319	Stay pending for several hours then fail. This simulates the gateway's behavior during payment provider outages that cause the provider to be unable to immediately indicate whether or not it received a request from the gateway.
`12125551003`	200	Succeed after a short delay.
`12125551005`	200	Succeed after a 5-minute delay. This simulates the gateway's behavior when using a provider that takes a long time to process incoming requests.

Virtual Cross-Currency Payments

The gateway can be used to make cross-currency payments, in which the client sends a source currency and amount, and the recipient receives this amount in their destination currency. To facilitate these cross-currency payments, an FX trade is booked to convert between source and destination currencies. During integration, you can trigger scenarios to emulate these FX trades. These FX test scenarios are independent of the payment testing scenarios mentioned above and can be used together.

To test cross-currency payments, you must use the test provider. As above, no money is ever sent when using the test provider, and no payments or trades are ever booked when using the test provider or virtual FX options.

FX testing scenarios are triggered using request header values. These cause the FX trade associated with the request to succeed or fail in order to test failure cases. If no header value is passed, but payments are sent to the test provider with cross-currency details specified, a success case is used by default.

Header value	Status	Description
`SUCCESS`	Depends on `test` provider test scenario; defaults to 200	FX tade is successful; payment status is dependent on payment test scenario passed, if any.
`SIMPLE_FAILURE`	303	The foreign exchange trade request failed.
`SHORT_DELAY_FAILURE`	303	Simple Failure use case but with 10 second delay.
`LONG_DELAY_FAILURE`	303	Simple Failure use case but with 1 hour delay.

In order to use these testing scenarios, to your request headers, add:

fx-test-scenario: <SCENARIO_NAME>

Payment Provider Autodetection

In some cases, it is possible for the payment gateway to automatically determine which payment provider should be used for a given recipient account ID. For example, in some countries, mobile carriers are assigned phone number prefixes such that a given phone number can only ever belong to a customer of a particular carrier, in which case only that carrier's mobile money service can pay the recipient.

Autodetection is enabled by setting the payment provider name to the string autodetect in the request JSON. If possible, the gateway will determine which provider to use.

Autodetection is not always possible for a variety of reasons. The most common one is that a country's mobile carriers support phone number portability, such that a customer of carrier A can switch to carrier B and keep the same phone number. In that case there is no way for the payment gateway to determine which carrier to use. If the payment gateway is unable to autodetect the provider for a transaction's recipient account ID, the transaction will fail with status code 406 (provider autodetection failed).

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search