Overview

This guide would help in understanding the flow of how payment acceptance with PayID would work and how this would be integrated into your system using Cake's API. Every customer from whom a payin needs to be accepted would first be created as a counterparty.

Once we have the counterparty ID with us we can use it to create a payment session, which essentially just takes in the amount of money we want to charge the customer along with some additional data. Post the successful call of this API we would have a payment link with us which would be then used by the customer to collect a payin of the specified amount. Ideally the payment link generated as part of the create session API would be used to redirect your customer from your dashboard/flow. We would also be specifying a **redirect url **while creating a payment session which would give you control where the user would land when the customer completes the payment session.

We would now be going through the entire process in more detail.

Creating a PAYIN counterparty

A payin counterparty is a customer from whom we would want to collect a payment and we can get the fields required to create one by calling our API for getting the counterparty schema, this API let's us understand which fields are required for creating. This is what the request would look like for creating a payin counterparty

🚧

Please ensure that the combination of email and phone number is unique per PAYIN counterparty

curl --location 'https://sandbox.cakecapital.com/api/v1/send/counterparties/' \
--header 'Authorization: <BEARER_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "first_name": "Christopher",
    "last_name": "Jennings",
    "type": "INDIVIDUAL",
    "payment_rail": "PAYIN",
    "phone_number": "0485843212",
    "email": "[email protected]",
    "date_of_birth": "1995-09-31",
    "address": {
        "city": "Campbelltown",
        "state": "NSW",
        "line_1": "123 Charming avenue",
        "postal_code": "2563",
        "country_code": "AU"
    }
}'

After the successful API call we would get the counterparty ID which we would use in the next step to initiate a payment session

Create a new payment session

The API for creating a payment session lets you set the amount, counterparty and the redirect url. The link generated by this API is valid for 1 hour and multiple links can be created for a particular counterparty. The following is a representation of how the cURL for creating a session looks like

curl --location 'https://sandbox.cakecapital.com/api/v1/earn/payment-sessions/' \
--header 'Authorization: <BEARER_AUTH_TOKEN>' \
--header 'Content-Type: application/json' \
--data '{
    "amount": 700,
    "currency": "AUD",
    "counterparty_id": "70427a14-a236-4d90-81f5-03ed3b82ab5d",
    "order_id": "28b4b696-d2a2-43e0-a335-5249e1288081",
    "purpose": "GAMING_TOP_UPS",
    "source_url": "https://www.acmecorp.com",
    "redirect_url": "https://www.acmecorp.com/payment"
}'

Webhook events

Since most of this flow would be asynchronous we would be sending out webhook events at every step. Following is a list of the events which we would send out as part of the whole journey

📘

Follow the instructions here to set up your webhook url

Geting transaction details

Our webhook events would contain a transaction_id which can be queried using the API for fetching transaction details by ID. Ideally you would want to call this API as soon as you get any transaction related webhook and update your records with it.

👍

Please feel free to contact us in case you have any queries or questions regarding the integration. We also look forward to hear about suggestions to make our systems work better for your use cases