Receiving Payments

Learn how you can initiate checkout processes using our API or our JavaScript SDK

JavaScript SDK

Our JavaScript SDK provides a simple and convenient way to initialize checkout processes with Asyncpay. It's the easiest way to handle payments because it can be done by calling a single function. Here's a demo of the JavaScript SDK pop-up.

Initializing a checkout process

In order to initialize the checkout process, you need to pass in the customer information, and other relevant data the checkout SDK needs to create a payment request.

Every time you initialize a checkout process via the SDK or API, you're actually creating a new Payment Request and relaying the payment request via a Payment Channel

This table lists out all the relevant information the SDK would need:

Name	Required?	Description
publicKey	Yes	The public key of your business gotten from the Asyncpay dashboard.
amount	Yes	The amount you want to charge the user. (You don't need to convert to minimum amounts but it should be at most two decimal places.)
currency	No	Three letter currency code. Defaults to NGN
description	No	The description of the transaction
customerEmail	required if customerUUID and customer are absent	The email of the customer you want to charge
customerUUID	required if customerEmail and customer are absent	The UUID of the customer (on Asyncpay's records) you want to charge
customer	required if customerEmail and customerUUID are absent	The customer object of the customer. Using this option would create a customer on the user
reference	No	A uniquely generated reference to be tied to the payment request for your checkout session. This would be automatically generated on Asyncpay's servers if none is supplied during the request
paymentChannel	No	The payment channel you want to route the payment to. If you set a value here, the checkout goes straight to that payment channel without giving the user a choice.
successURL	No	The url to redirect the user to after a successful payment
cancelURL	No	The url to redirect the customer to if the user cancels the checkout page
onCancel	No	A JavaScript function to call after the user cancels the checkout page
onClose	No	A JavaScript function to call whenever the checkout page closes irrespective of why the checkout page closed.
onSuccess	No	A JavaScript function to call after the user has successfully completed checkout
logo	No	A URL pointing to the logo to show up on the checkout pop-up if you want to override the logo set on the dashboard

In Asyncpay, a payment request is always tied to a customer, Asyncpay would need to link each payment request to a new customer or an existing customer on your business. You can create a customer by simply providing the customer information on the checkout object and use the email or UUID to identify that customer on subsequent payments.

This table shows the structure of a customer object. You should use this if you want to create a customer while initializing a payment request:

Name	Required?
firstName	Yes
lastName	Yes
email	Yes
phoneCode	Required with phoneNumber
phoneNumber	No
addressLine1	No
addressLine2	No
city	No
state	No
country	No
zip	No

These information can be retrieved from your database if they are stored there or entered by the user on a form to initialize the process.

You can view our guides that shows how to receive payments with Asyncpay on a React and Vue

After the payment

The AsyncpayCheckout function supplies a number of callbacks that can be used to perform actions after a user attempts a payment. As shown in the table above, there are five major ways we can do something after a payment is completed:

• onSuccess - The SDK fires the function supplied to this callback when the payment is successfully completed. It is important to verify the transaction before giving your customer value here.

• onClose - The SDK fires this function whenever the checkout pop-up is closed, irrespective of whether the payment was successful or not.

• onCancel - The SDK fires this function whenever the customer closes the pop-up manually.

• successURL - The SDK redirects the user to the URL specified after a successful payment. This URL takes precedence over onSuccess callback. This means if both are provided, the SDK would redirect and ignore the callback.

• cancelURL - The SD redirects the user to the URL specified if the user closes the pop-up manually. This URL takes precedence over onCancel callback. This means if both are provided, the SDK would redirect and ignore the callback.

Verifying Payment Status

After a successful payment, it is important to verify the status of the payment request on the Asyncpay servers before giving your user value. There are two ways to verify a payment; webhooks and by checking the status of the payment request via the API. We do this as an extra security measure to ensure the payment has been verified by the payment provider and that Asyncpay has confirmed this verification.

When using the webhook, you would need to listen for the payment_request.successful event. This event would always contain the payment request as well as other metadata. If using the API, you would fetch the payment request. Regardless of the method being used, you would need to check for two things on the payment request object:

Property	Description
status	You would need to check that this is successful. A succesful status means that the a payment has been made and verified for the payment request.
amount	You should check the amount to see that it tallies with what you have on record.

A payment request always contains information about the payment provider that was used to carry out the transaction. The information about the transaction from the payment provider is always stored in the last_transaction property of the payment request.

It is called last transaction because a payment request could be relayed multiple times to different multiple payment providers in its lifecycle. Any unpaid transaction is voided before a new one is created, this means a payment request could have multiple transactions but we only care about the last one for a successful payment request.

All payment verifications should be done on a server backend and never on the frontend. The API works with your secret key and it should never be used on the frontend since these keys would be visible to a malicious user. Your frontend should make a request to your server to verify transactions via Asyncpay's servers.

API Redirect

When we use the checkout SDK endpoint to create a request, we're simply creating a payment request. If you want to receive payments without using the checkout SDK, you can simply create a payment request via the API and redirect your users to the checkout page created by the payment provider. The Initiate Payment Request endpoint is used to create a payment request on Asyncpay via the API. You can learn more by visiting our API documentation.

Never access the APIs from your frontend as this will expose your secret key. Always perform API requests from your secure backend server.

This table lists out all the parameters that the Initiate Payment Request endpoint can receive:

Name	Required?	Description
amount	Yes	The amount you want to charge the user. (You don't need to convert to minimum amounts but it should be at most two decimal places.)
currency	No	Three letter currency code. Defaults to NGN
description	No	The description of the transaction
reference	No	A uniquely generated reference to be tied to the payment request for your checkout session. This would be automatically generated on Asyncpay's servers if none is supplied during the request
success_redirect_url	No	The URL to redirect the user to after a successful payment
failure_redirect_url	No	The URL to redirect the user to after a failed payment (Usually after the user cancels the payment since most providers allow a user try multiple times after a failed payment)
payment_channel	No	This specifies the payment channel through which the payment request should be directed, triggering an automatic relay of the created payment request to the specified payment channel.
customer_uuid	Required if customer and customer_email are absent	This specifies the UUID of the customer that this payment request should be tied to.
customer_email	Required if customer and customer_uuid are absent	This specifies the email of the customer that this payment request should be tied to.
customer	Required if customer_email and customer_uuid are absent	This specifies an object containing the customer data. It can be used to create a customer while initializing a payment. It create a customer (or uses the one that exists with the specified email) to initialize a payment transaction.

The table below shows the possible values of the customer object mentioned above:

Name	Required?
first_name	Yes
last_name	Yes
email	Yes
phone_code	Required with phone_number
phone_number	NO
address_line_1	No
address_line_2	No
city	No
state	No
country	No
zip	No

When should you use the API Redirect

The API Redirect comes into play when you're dealing with mobile or desktop applications that operate outside the web environment. Currently, Asyncpay offers an SDK tailored for web applications. However, if you're aiming to serve mobile or desktop applications, and you need to construct your unique checkout process, the API Redirect becomes an optimal choice.

By utilizing the API Redirect approach, you have the freedom to design your frontend and leverage your server to trigger a customized checkout process. It's worth noting that while a web SDK is available now, we're actively developing SDKs specifically designed for mobile and desktop environments that will be available very soon.

Relaying a Payment Request

Asyncpay allows you to relay a payment request if it fails. One of the easy ways to do this would be to set a URL on the failure_redirect_url that does one of the following:

1. Redirects the user to a page where they can choose a different payment channel like the JavaScript SDK does

2. Redirects the user to an endpoint on your server where you can have conditions for doing a secondary relay.

To relay a payment request, you can make a call to the Relay Payment Request endpoint. All you need to specify to this endpoint is the reference of the payment request and the payment channel you wish to relay the payment to. Asyncpay would automatically void the last transaction created on the payment request and create a new one with the payment channel specified.

Name	Required?	Description
payment_request_ref	Yes	The reference of the payment request. This is returned from the Initialize Payment Request endpoint
payment_channel	Yes	The payment channel you wish to relay the payment request to.

After relaying a payment request, the process is the same as above, the endpoint returns a similar response to the Initialize Payment Request endpoint and you can redirect your user to the URL returned in the response.

After the payment

Asyncpay's Initialize Payment Request endpoint provides two paramateters that allow you handle payment requests after a payment has been made:

1. success_redirect_url - This specifies the URL to redirect the user to after a successful payment. Ideally, this should point to an endpoint on your server you can use to verify that the payment was successful and grant the user value.

2. failure_redirect_url - This specifies the URL to redirect the user to after the user cancels after a failed payment attempt (Most payment providers don't redirect immediately a payment attempt fails. They allow the user try with different payment instruments until the user cancels). This could either redirect to a frontend on your page where the user could attempt with a different channel, or an endpoint on your server where you have protocols for relaying the payment.

Verifying Payment Status

Verifying the payment status is done in the same way as stated above. When we redirect to the URLs, we provide the payment request reference in the reference query parameter. You can use this reference to query the Retrieve Payment by Reference endpoint to verify whether the payment has been verified before giving your customer value.

You can also use the webhook to verify the payment. We would send a payment_request.successful event when the payment request has been completed and verified on our server.

Never access the APIs from your frontend as this will expose your secret key. Always perform API requests from your secure backend server.