Skip to main content

​
Overview

Payaza supports Apple Pay and Google Pay as collection channels. You initiate the payment from your server using the mobile payment API which generates a payment URL for the customer to access, and the customer authorizes the charge through their device’s native wallet experience.
Apple Pay works on Safari (iOS and macOS). Google Pay works on Chrome and Android browsers. Always provide a fallback payment method for customers who do not have a supported wallet configured on their device.

​
Key Requirements

Use your public API key encoded in Base64 for all wallet payment requests. See the Authentication guide for setup instructions.
Set these headers on every request: 
{
  "Authorization": "Payaza <Your public API key encoded in base 64>",
  "Content-Type": "application/json"
}
Make sure your Collection webhook URL is saved on the dashboard. See the Webhooks guide for setup instructions.

​
Endpoints

MethodEndpointDescription
POST/merchant-collection/mobile_payment/initiateInitiate an Apple Pay or Google Pay payment
GET/merchant-collection/transfer_notification_controller/transaction-queryQuery transaction status by transaction_reference

​
How it works

1

Initiate the payment

Your server calls the Initiate endpoint with the customer details, amount, and payment_option set to "APPLEPAY" or "GOOGLEPAY" which generates a payment URL.
2

Customer authorizes

The customer views the payment URL and sees the native Apple Pay or Google Pay checkout modal on their device and authenticates with Face ID, Touch ID, or their device PIN.
3

Receive the outcome

Payaza fires a webhook to your configured URL when the payment completes or fails. Use the Transaction Status Query endpoint as a fallback if a webhook is not received in time.

​
Step 1 — Initiate the payment

curl --request POST \
  --url https://api.payaza.africa/live/merchant-collection/mobile_payment/initiate \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 2,
    "first_name": "John",
    "last_name": "Doe",
    "payment_option": "APPLEPAY",
    "description": "Support",
    "transaction_reference": "TX20251109",
    "redirect_url": "https://redirect.url/success",
    "cancel_url": "https://redirect.urlcancel",
    "error_url": "https://redirect.url/error",
    "country_code": "NGN",
    "currency_code": "USD"
  }'

​
Request parameters

ParameterTypeRequiredDescription
transaction_referencestringYesYour unique reference for this payment. Must be unique per transaction
payment_optionstringYesWallet type — "APPLEPAY" or "GOOGLEPAY"
amountnumberYesAmount to collect from the customer
currency_codestringYesISO currency code — e.g. "USD", "NGN"
country_codestringYesISO currency code for the transaction country — e.g. "NGN"
descriptionstringYesDescription shown on the customer’s payment confirmation
first_namestringYesCustomer’s first name
last_namestringYesCustomer’s last name
redirect_urlstringYesURL to redirect the customer to after successful payment
cancel_urlstringYesURL to redirect the customer to if they cancel
error_urlstringYesURL to redirect the customer to on payment error

​
Sample response

{
  "status": true,
  "message": "payment initiated successfully",
  "data": {
    "error_url": "https://redirect.url/error",
    "merchant_reference": "TX20251109",
    "payment_option": "GOOGLEPAY",
    "transaction_amount": 2,
    "slug_name": "dev-guide-test",
    "currency": "USD",
    "paymentUrl": "{{paymentUrl}}",
    "transaction_reference": "TX20251109",
    "cancel_url": "https://redirect.urlcancel",
    "redirect_url": "https://redirect.url/success"
  }
}

​
Step 2 — Query transaction status

Use this endpoint to confirm the final outcome of a payment. Call it after initiating, or as a fallback if a webhook is not received within your expected timeout.
cURL
curl --request GET \
  --url 'https://api.payaza.africa/live/merchant-collection/transfer_notification_controller/transaction-query?transaction_reference=TX20251109' \
  --header 'Authorization: Payaza <Your public API key encoded in base 64>'

{
  "message": "Transaction data found",
  "data": {
    "transaction_reference": "P-C-20260306-41XUJ9AISE",
    "amount_received": 5,
    "transaction_fee": 0.05,
    "transaction_status": "Completed",
    "sender_name": "Test  Test",
    "sender_account_number": null,
    "source_bank_name": "NA",
    "initiated_date": "2026-03-06 17:14:44.414486",
    "current_status_date": "2026-03-06 17:15:10.136189",
    "currency": "USD",
    "session_id": "TRN99637191655A",
    "merchant_transaction_reference": "TX213139dz",
    "transaction_type": "Apple Pay",
    "virtual_account_number": null,
    "status_reason": null
  },
  "success": true
}

​
Errors

ErrorCauseFix
"Kindly check the provided Authorization"Invalid or missing API keyRe-encode your key and use the Payaza <key> format
"Transaction Reference already exists"Reused transaction_referenceGenerate a unique reference per payment attempt
"Payment option can be either GOOGLEPAY or APPLEPAY"Invalid payment_option valuePass exactly "GOOGLEPAY" or "APPLEPAY"
"Payment option is currently not available via this channel"Unsupported currency codeUse a supported currency for wallet payments
"Transaction not found"transaction_reference does not existVerify the reference and retry
See the full Errors reference for more detail.

​
What’s next

Card Collections

Accept card payments directly via the API.

Webhooks

Receive real-time payment notifications from Payaza.