Payment API

Democrance has a payment process that is designed to support multiple payment gateways. The general flow is that the customer will arrive at a checkout/summary page, and will click a button to check out/purchase the policy.

At this point, the democrance back end should be notified that the user wishes to continue to payment, and the /api/v3/payment/token/ endpoint should be called. This will generally return a token from the payment gateway, along with a URL to which the user should be redirected to, or their browser should POST to. The token will be tied to the policy that the customer is trying to purchase and can be used to check for payment completion at a later stage.

The redirect or post must be handled by the client application.

Following the redirection the customer will land on a credit card (or points/loyalty program) screen. Once they have completed the payment process, payment gateway will redirect the customer to the following path on the democrance server.

/api/v3/payment/process/

This will trigger the completion of the payment process. Once we have recorded the payment and activated or extended the policy as necessary, we will redirect the customer back to a URL of your choosing.

Should payment fail, it is up to the client application to re-try payment

At this point we can redirect the client back to a payment completion page on your client-application. This is something democrance will need to configure on a per-deployment/per-payment processor basis.

Should the return call fail, the democrance platform will automatically check the status of incomplete payments periodically. If the background process catches payments that have been missed, the policy and requisite policy sms or email will be issued once we have established payment.

/api/v3/payment/token

URL	/api/v3/payment/token
Methods	GET

The above endpoint takes the following parameters:

url	the url you would like the backend to redirect to on completion of payment.
policy_number	the current/temporary policy number.

Here is an example response from the server.

{
    "url": "A url to redirect to - this depends on the payment gateway used",
    "token": "A reference string from the payment gateway that identifies this payment request",
    "form": "An html/js snippet which may need to be executed to POST to the payment gateway",
    "status": "OK or a different message indicating an error",
}

List payment gateways

URL	/api/v3/payment/gateways/?policy_number=<policy number>
Methods	GET, POST

Key	Type	Description
policy number	String	Optional GET parameter of the policy number that you wish to purchase.

The above endpoint provides a way to get a list of possible payment gateways that can be used to purchase the policy. The policy number is optional; however, we strongly recommend providing it. Providing the policy number enables us to check for, and return any product specific options, which might not otherwise be available.

The response from the server will be a list of gateways, even if there is only a single gateway available, an example is shown below:

[
    {
        "gateway": "payfort-aed",
        "name": "Payfort",
        "provider": "payfort"
    },
    {
        "gateway": "invoice",
        "name": "Invoice",
        "provider": "Democrance"
    },
]

Key	Type	Description
gateway	String	The unique identify which you will need to submit in later steps.
name	String	A user friendly representation of the gateway, which can be used for display purposes.
provider	String	The provider of the gateway

Initiate payment

URL	/api/v3/payment/initiate/
Methods	POST

Once you know the payment gateway ID, you can initiate the payment process by making a POST request to the above endpoint. The POST payload should contain the following data

{
    "policy_number": "<policy number>",
    "gateway": "<selected payment gateway key>"
}

Key	Type	Description
policy_number	String	The policy number of the policy that you want to initiate a payment for
gateway	String	The unique gateway identifier that was returned from the list payment gateway endpoint

The JSON response from the server will take the following format

{
    "action": "<action to take>",
    "url": "<redirection URL>",
    "token": "<unique payment token>"
}

Key	Type	Description
action	String	This will be one of a set of predefined values (see below).
url	String	A redirection URL which if payment is required should be used. If no redirection is required, this value will be null.
token	String	A unique token related to the payment request. This will be needed.

Action	Description
Payment required
No payment required
Payment to be invoiced

Validate Payment Session

URL	/api/v3/payment/validate-session/?token=signedtokennumber
Methods	POST

Once you know the payment gateway ID an payment been initiate you create payment session at the service Provider if that is needed and shared with frontend side Ex : Apple Pay by making a POST request to the above endpoint. The POST payload should contain the following data and payment need to be passed by url

{
    "policy_number": "<policy number>",
    "gateway": "<selected payment gateway key>"
}

Key	Type	Description
policy_number	String	The policy number of the policy that you want to initiate a payment for
gateway	String	The unique gateway identifier that was returned from the list payment gateway endpoint

The JSON response from the server will JSON formatted of payment gateway create session api’s response. example: Apple Pay validate session api response.

{
    "epochTimestamp": 1668406930665,
    "expiresAt": 1668410530665,
    "merchantSessionIdentifier": "SSHB945391358214DD5AF88F808FB23CE6F_A0E617ED4A56A343E07C6E1255BD4098423B3A8E1243236462D07B14B4A0F7C3",
    "nonce": "2dac54f4",
    "merchantIdentifier": "332541C0861E96D765BA8C2BB59D7462A8C46F2CD3FFC7E60792E7BCBBECB5F3",
    "domainName": <Payment Domain Name>,
    "displayName": <payment session Display Name>,
    "signature": <payment session sigature>,
    "operationalAnalyticsIdentifier": "Tree's Policy:332541C0861E96D765BA8C2BB59D7462A8C46F2CD3FFC7E60792E7BCBBECB5F3",
    "retries": 0,
    "pspId": "332541C0861E96D765BA8C2BB59D7462A8C46F2CD3FFC7E60792E7BCBBECB5F3"
}

Payment status

URL	/api/v3/payment/status/
Methods	GET

Payment Completed

URL	/api/v3/payment/complete/
Methods

Generate Tax Invoice

URL	/api/v3/payment/<payment reference>/tax-invoice/
Methods

Generate Receipt

URL	/api/v3/payment/<payment reference>/tax-invoice/
Methods