PaymentIntent
PaymentIntent
’s statusPaymentIntent
object is used to represent the intent to collect a payment from a customer. It keeps track of fees and various payment attempts throughout the processing.
The PaymentIntent
must be created on the merchant server with an amount
, a currency
, your customer reference and your purchase reference.
Create a payment intent
Here is a sample of request to that endpoint:
id
is the unique reference to the PaymentIntent
, it will be used to attempt paymentstoken
is a JSON Web Token (JWT) that will be used to authenticate the payment requestreference
: no special characters are allowed. Trying to use special characters here will result in a 400 Bad Request
error.
Allowed characters are letters, numbers, hyphen, underscore, dot and space. Here’s the list in the regular expression format : A-Za-z0-9\-_.
.
PaymentIntent
is successfully created, it will be possible to collect payment information with the final customer and attempt a Payment
.
To attempt a Payment
, the paymentMethod
and all required field that are described in the API reference must be specified .
Attempt a payment
As this route does not require your private API_KEY
, the payment request could be made directly on the client side (from the client himself), using the previously retrieved JWT token
to authenticate the request.
HTTP 201
with the full PaymentIntent
object in the response body will be returned.
Notice that the status is now processing
and the payments
array contains the newly created Payment
attempt.
The payment id
can now be saved to identify your payment attempt in the list as more than one payment may be attempted for one PaymentIntent
.
PaymentIntent
for status updates, we recommend to use webhooks.
Please take a look at Webhooks Integration to see how to implement them.
Register to payment
or payment_intents
related events.
By using this method, the merchant server will be notified once the Payment
or the PaymentIntent
is updated.
This way, implementing mechanisms to poll the status is not necessary, rate limiting won’t be applied and potential latency issues will be avoided.
Also in case of high payment traffic, it will reduce the load on the merchant server and consequently on HUB2 servers.
HTTP 429 - Too Many Requests
will be returned in this case. Please take this in consideration while implementing the check status polling.PaymentIntent
.status
is processing
OR action_required
. Continuously polling payment_required
, successful
or failed
PaymentIntent
will result in source IP address being throttled or temporarily banned.PaymentIntent
status will be action_required
. This status mean that the payment attempt requires a manual action from the user to authenticate or validate the payment.
Payment
object will contain a nextAction
object that will describe the type of the action that will be required from the user.
"nextAction": { "type": "otp", "message": "Mode Sandbox. Entrez un numéro à 4 chiffres pour authentifier le paiement." }
.nextAction.message
should now be displayed to the final customer to let him know what he should do. The action indicates the customer to validate the Payment. There are different types for the action :
redirection
action type provides all the information to redirect the customer to an external page.ussd
action type indicates to the user the USSD procedure to follow to validate the payment.otp
action type indicates to the final customer how to generate an One Time Password (OTP). This type of action requires the client to enter the OTP code into a field that will be sent to the dedicated API Route. Please note that some providers allow to pass the OTP code directly in the payment attempt request (see otp
field mobileMoney
object).PaymentIntent
) as described previouslybank_transfer
as the payment methodPaymentIntent
object containing the bank transfer payment details, including the unique reference generated for the bank transfer.