Accept Payment

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

Understanding the Payment Flow

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

Integration Steps

Obtain API key: Get your API key from the Configurations page.

2Initiate a transaction and get a payment link.

3Redirect customer to the payment page.

4Handle payment confirmation.

Initiate Transaction and Get Payment Link

Endpoint

POSThttps://api.admaspay.com/api/v1/initiate/transactions?command=initiate

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	Your unique transaction reference
first_name	String	No	Customer's first name
last_name	String	No	Customer's last name
email	String	No	Customer's email address
currency_code	String	No	ETB for Birr, USD for Dollar
callback_url	String	No	URL called when payment is successful
return_url	String	No	URL to redirect after successful payment

Example Integration

Success Response

200 OK

{
    "checkout_url": "https://dashboard.admaspay.com/checkout?uid=c23e39b7-8945-42a4-81ca-a63d2fd4d7",
    "status": "success",
    "message": "Initiated checkout link."
}

Error Response

Error

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

Redirect Customer to Payment Page

After successfully initiating a payment transaction, you'll receive a response containing checkout_url. Redirect your customer to this URL where they will complete their payment on AdmasPay's secure checkout page.

Example redirect in JavaScript:

window.location.href = response.data.checkout_url;

Handle Payment Confirmation

After a customer completes payment, you need to confirm the transaction status to fulfill orders or services. The following events occur when payment is completed:

1. Return URL Redirect

Customer is automatically redirected to your return_url.

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

2. Callback URL Notification

AdmasPay sends a notification to your callback_url with transaction details.

3. Webhook Notification

If enabled, detailed payment data is sent to your webhook endpoint including customer details, payment method, etc.

Important: The callback_url and webhook are the most reliable confirmation methods. Always verify transactions server-to-server before fulfilling orders.

Callback Parameters

When payment is completed, your callback URL receives these parameters:

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

Example Callback Handler

Callback Handler

{
   "txn_ref": "admaspay_a23456",
   "custom_ref": "sj292dmsid",
   "status": "success"
  }

Your callback handler should verify this transaction using the verify endpoint. For more details, see Verify Payment.