The Payment requests API allows you to initiate payment requests for your customers in your Asyncpay business
Initiate Payment Request
post
This endpoint is used to initiate a payment request. A payment request is an object that initiates and stores the entire lifecycle of a payment for a customer. A payment request can be initiated for checkout, for saving a payment method, or for initiating/subscribing a customer to a subscription plan.
The endpoint accepts different fields depending on the use case for initiating the payment request.
The save_payment_method boolean flag can be used to tell Asyncpay to save a payment method. This saved payment method can be found later in the /v1/customers/{CustomerUUID}/payment-methods endpoint. You can then later make a request to charge the customer's payment method.
The subscription_plan_uuid tells Asyncpay that this payment request is intended for subscribing a customer to a subscription plan. When a payment request is initiated in this mode, the checkout process goes as usual, but at the end, Asyncpay would automatically save the customer's payment method and subscribe the customer to the provided plan, and subsequently charge the customer with that payment method for the plan at the next subscription billing cycle.
The success_redirect_url and the failure_redirect_url redirect the customer at the end of a payment request to a specified endpoint. This can be used to take the customer back to your application or to trigger processes that grant the customer value after a successful payment.
Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional
The UUID of the customer that is initiating this payment request. This field is required if customer_email and customerfields are absent.
customer_emailstring · nullableOptional
The email of the customer that is intiating this payment request. This field is required if customer_email and customerfields are absent.
amountany ofOptional
The amount of the payment request. This field is required except a subscription_plan_uuid is proviided since the subscription plan will determine the subscription.
stringOptional
or
numberOptional
or
nullOptional
referencestring · nullableOptional
Your unique reference of this payment request.
currencystring · nullableOptional
The currency of the payment. It must be a three character currency code matching the ISO 4217 standard for currencies
descriptionstring · nullableOptional
A description of the payment request. This field is only required if subscription_plan_uuid is not provided
payment_channelstring · nullableOptional
The slug of the payment channel that Asyncpay should route this payment through.
success_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a successful payment
failure_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a cancelled payment
subscription_plan_uuidstring · nullableOptional
The UUID of a subscription plan. This field should be provided if this payment request is initiated with the intent of subscribing the customer to a plan
save_payment_methodboolean · nullableOptional
A boolean flag that tells Asyncpay whether or not to save the payment method the user uses to make this payment.
is_trialboolean · nullableOptional
A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.
meta_dataobject · nullableOptional
An arbitrary object to store additional data for the payment request
Responses
201Success
application/json
400Error
application/json
post
/v1/payment-requests/
Relay Payment
post
This endpoint is responsible for routing payment requests to designated payment providers. If a payment channel is specified during initialization, the request is automatically relayed to the designated provider. Additionally, a payment request can be rerouted to a different provider as long as its status is either new or open.
Once the payment is in one of these statuses, it can be relayed to a new provider, even if it was previously routed to a different one. Rerouting a payment invalidates any prior transactions with previous payment providers. To relay a payment, you simply need the reference of the payment request and the desired payment channel.
Authorizations
AuthenticationstringRequired
Body
payment_request_refstringRequired
The UUID or reference of the payment request you want to relay
payment_channelstringRequired
The slug of the new payment channel you want to route this payment request through
Responses
201Success
application/json
post
/v1/payment-requests/relay
201Success
Save Payment Method
post
This endpoint is used to save a customer's payment method.
This endpoint initiates a payment request and a checkout process with the sole intent of capturing and saving the customer's payment method; as such, it doesn't require an amount field.
This endpoint automatically charges the smallest fee the underlying payment channel requires to tokenize and save a reusable payment instrument, such as a card.
Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional
The UUID of the customer that is initiating this payment request. This field is required if customer_email and customerfields are absent.
customer_emailstring · nullableOptional
The email of the customer that is intiating this payment request. This field is required if customer_email and customerfields are absent.
referencestring · nullableOptional
Your unique reference of this payment request.
payment_channelstring · nullableOptional
The slug of the payment channel that Asyncpay should route this payment through.
success_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a successful payment
failure_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a cancelled payment
Responses
201Success
application/json
post
/v1/payment-requests/save-payment-method
201Success
Charge Payment Method
post
This endpoint is used to make a charge to a customer's saved payment method.
It expects many of the same parameters you attach to the /v1/payment-requests/ to create a new payment request.
The major difference between this endpoint and the /v1/payment-requests/ is that this endpoint does an immediate charge on the payment method you provide, and expects that a payment method has been saved on the system, while the other endpoint gives your users an interface to specify their payment method to carry out the transaction.
Behind the scenes, both endpoints still initiate a payment request and process it in the same way.
N.B. This endpoint does not feature a payment_channel field, because payment methods would be tokenized with a specific payment channel, for instance, if you saved a card with Paystack, you can't use Stripe to process that same payment method. You'll have to create a new payment method with that payment channel for now.
Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional
The UUID of the customer that is initiating this payment request. This field is required if customer_email is absent.
customer_emailstring · nullableOptional
The email of the customer that is intiating this payment request. This field is required if customer_email is absent.
payment_method_uuidstringRequired
The UUId of the payment method you want to charge
amountany ofOptional
The amount of the payment request. This field is required except a subscription_plan_uuid is proviided since the subscription plan will determine the subscription.
stringOptional
or
numberOptional
or
nullOptional
referencestring · nullableOptional
Your unique reference of this payment request.
currencystring · nullableOptional
The currency of the payment. It must be a three character currency code matching the ISO 4217 standard for currencies
descriptionstring · nullableOptional
A description of the payment request. This field is only required if subscription_plan_uuid is not provided
subscription_plan_uuidstring · nullableOptional
The UUID of a subscription plan. This field should be provided if this payment request is initiated with the intent of subscribing the customer to a plan
is_trialboolean · nullableOptional
A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.
meta_dataobject · nullableOptional
An arbitrary object to store additional data for the payment request
Responses
201Success
application/json
post
/v1/payment-requests/charge-payment-method
201Success
Fetch Payment Request by Reference
get
This endpoint fetches a single payment request using the payment request reference or UUID.
Authorizations
AuthenticationstringRequired
Path parameters
PaymentRequestRefstringRequired
The UUID or reference of the payment request you want to fetch
This endpoint provides a paginated list of payment requests within your business. You can customize the number of items per page by using the per_page query parameter. Additionally, you have the option to filter the returned payment requests based on their status using the status query parameter.
Authorizations
AuthenticationstringRequired
Responses
200Success
application/json
get
/v1/payment-requests/
200Success
Subscribe to Subscription Plan
post
This endpoint is similar to the initiate payment request, but it is used exclusively to subscribe a customer to a plan.
This endpoint initiates a payment request and a checkout process with the sole intention of subscribing the customer to a specified plan.
A customer can either be subscribed to a plan in trial mode (which charges the lowest possible charge a payment channel accepts to save a payment method) or in the default mode that charges the customer the regular subscription fee defined in the subscription plan.
Authorizations
AuthenticationstringRequired
Body
customer_uuidstring · nullableOptional
The UUID of the customer that is initiating this payment request. This field is required if customer_email and customerfields are absent.
customer_emailstring · nullableOptional
The email of the customer that is intiating this payment request. This field is required if customer_email and customerfields are absent.
referencestring · nullableOptional
Your unique reference of this payment request.
payment_channelstring · nullableOptional
The slug of the payment channel that Asyncpay should route this payment through.
success_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a successful payment
failure_redirect_urlstring · nullableOptional
A URL to redirect the customer to after a cancelled payment
subscription_plan_uuidstringRequired
The UUID of the subscription plan.
save_payment_methodboolean · nullableOptional
A boolean flag that tells Asyncpay whether or not to save the payment method the user uses to make this payment.
is_trialboolean · nullableOptional
A booelan flag that tells Asyncpay that you are subscribing the user to a plan in trial mode. In this mode, Asyncpay would charge the lowest possible fee that the payment channel supports for the first billing cycle, after which it would charge the regular subscription fee.
meta_dataobject · nullableOptional
An arbitrary object to store additional data for the payment request
