Cash Collection Example

Introduction

In this example we'll go through all of the steps and give examples on what you'll need to do to implement a call to payout cash collection transaction. Once you've read through this guide you'll know everything that is required by us for you to use our system.

We require that all implementations to our site pass our onboarding test before we allow partners to access our prouction site. This example shows the preferred solution to all requirements we have, so following this example will make sure you will adhere to our requirements and will hopefully pass our onboarding test.

Authentication

First thing is that you'll need to authenticate to use our site. You can get your API key and secret by contacting our team.

You need to contact us before you are allowed to use our sandbox environment. Once you reach out to us you'll also be invited to our Skype group where you can post questions about our API that will be answered by our Engineering team. We prefer technical communication to go through this Skype group.

Once you obtain your api key and secret you'll need to set up your environment with them:

See the authentication documentation for more details on the authentication process.

Lock

To prevent cash collection transaction from being paid multiple times we are using lock mechanism.

When bank is trying to payout transaction, we lock transaction and it become allowed for this specific bank only. This lock is not permanent, and will expire in 1 hour after your last payout attempt.

We are using branch_id to lock transaction and prevent it from being paid at multiple branches of the bank. This lock is not permanent, and will expire in 30 minutes after your last payout attempt.

POST /cash_collection/[REFERENCE]/lock

{
    "branch_id": "unique-branch-id"
}

Lock considered successful if you received 200 status code.

Payout

To payout cash collection transaction, you have to obtain the reference and code from the recipient, and also specify the bank branch_id at which recipient is trying to obtain the funds.

You should call this endpoint before giving the funds to the recipient.

POST /cash_collection/[REFERENCE]/payout

{
    "code": "123456",
    "branch_id": "unique-branch-id"
}

Payout considered successful if you received 200 status code.

See the architecture documentation for more details on the status codes.

Retrieve

Occasionally you might want to query a cash collection transaction in our system so you'll be able to update it on your end. You can use the reference for this.

Both sender and recipient may not contain fields depending on the provided information. We have marked the fields that will always be present in the response with // always comment.

GET /cash_collection/[REFERENCE]

{
    "data": {
        "id": "426fb3c1-6ba3-49f7-9990-1f932e8eff64", // always
        "state": "initial", // always
        "corridor": {
            // corridor information
        },
        "transaction": {
            "id": "85ad4973-d19d-454f-9b21-a19a89a24853", // always
            "type": "cash", // always
            "state": "approved", // always
            "output_currency_code": "USD", // always
            "output_amount": "1.00", // always
            "output_amount_in_cents": "100", // always
            "reference": "123465798", // always
            "sender": {
                "type": "person", // always
                "state": "approved", // always
                "first_name": "John", // always
                "last_name": "Doe", // always
                "birth_date": "1997-01-01", // always
                "gender": "male",
                "country_code": "USA", // always
                "street": "Broadway street",
                "postal_code": "10001",
                "city": "New York"
            },
            "recipient": {
                "state": "approved", // always
                "first_name": "Jane", // always
                "last_name": "Doe", // always
                "birth_date": "1970-01-01",
                "gender": "female",
                "country_code": "NGA", // always
                "street": "Street",
                "postal_code": "12345",
                "city": "City",
                "phone_number": "+14158586273", // always
                "email": "[email protected]"
            },
            "created_at": "2021-05-21T19:10:09.000000Z",
        }
    }
}