Accept Payment

This documentation explains how to integrate AdmasPays payment gateway into your application to securely accept payments from customers.

Understanding the Payment Flow

Your Server: Calls AdmasPay API to initiate a transaction.
AdmasPay: Returns a unique payment_url in the response.
Customer: Completes payment on AdmasPay's secure checkout page.
AdmasPay: Redirects back to your return_url (if provided) after payment.

Integration steps

Obtain API key: you can get an API key Link to how to generate an API key.
Initiate a transaction and get a payment link.
Redirect customer to payment page
Handle payment confirmation.

Initiate transaction and get a payment Link

Endpoint

https://api.admaspay.com/api/v1/initiate/transactions?
Command= initiate

Method : POST

Headers

Pass your api key as a bearer token in the request header to authorize this api.

Authorization : Bearer YOUR_API_KEY

Content-Type : application/json

Request Parameters

Parameter	Type	Required	Description
phone_number	String	Yes	Customer's phone number
amount	Number	Yes	The payment amount
txn_ref	String	Yes
first_name	String	No
last_name	String	No
email	String	No
currency_code	String	No
callback_url	String	No
return_url	String	No

Example Integration

Success Response:

{
    "checkout_url":"https://dashboard.admaspay.com/checkout?uid=c23e39b7-8945-42a4-81ca-a63d2fd4d7"
}

Error Response:

{
    "type": "about:blank",
    "title": "not authenticated",
    "status": 401,
    "instance": "/api/v1/initiate/transactions",
    "message": "error.http.401"
}

Redirect the customer to payment page

After successfully initiating a payment transaction you'll receive a response containing checkout_url. you need to redirect your customer to the link checkout_url and we will display our checkout page customer to complete their payment.

Example In web using javascript you can redirect it
window.location.href = response.data.checkout_url;

Handle payment Confirmation

After a customer completes payment using your AdmasPay payment link, you need to confirm the transaction status to fulfill orders or services.

Those things will happen when payment is done.

Return url redirect: Calls customer is automatically redirected to your return_url.

Note: This is client-side only - don't rely solely on this for order fulfillment

Callback url notification:
Webhook Notification: If enabled, send detailed payment data to your webhook endpoint. more comprehensive than callback URL (includes customer details, payment method, etc.)

Note: The callback_url and webhook are the most reliable confirmation methods. The return_url is for customer experience only - never use it as payment proof. Always verify transactions server-to-server before fulfilling orders.

Handle payment Confirmation

After a customer completes payment using your AdmasPay payment link, you need to confirm the transaction status to fulfill orders or services.

Parameter	Description
txn_ref	The unique transaction reference you provided to initiate transaction
custom_ref	Admaspay internal reference
status	The status of the transaction

Example:

{  
   "trx_ref": "admaspay_a23456", 
   "custoom_ref": "sj292dmsid", 
   "status": "success"
  }

Your callback handler should verify this transaction using the verify endpoint to confirm the transaction and get the details of the transaction. For more detail Verify Payment.