Apple Pay & Google Pay

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

Method	Endpoint	Description
`POST`	`/merchant-collection/mobile_payment/initiate`	Initiate an Apple Pay or Google Pay payment
`GET`	`/merchant-collection/transfer_notification_controller/transaction-query`	Query transaction status by `transaction_reference`

How it works

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.

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.

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",
    "email_address: "johndoe@email.com",
    "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"
  }'

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": "GOOGLEPAY",
    "description": "Support",
    "email_address: "johndoe@email.com",
    "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

Parameter	Type	Required	Description
`transaction_reference`	`string`	Yes	Your unique reference for this payment. Must be unique per transaction
`payment_option`	`string`	Yes	Wallet type — `"APPLEPAY"` or `"GOOGLEPAY"`
`amount`	`number`	Yes	Amount to collect from the customer
`currency_code`	`string`	Yes	ISO currency code — e.g. `"USD"`, `"NGN"`
`country_code`	`string`	Yes	ISO currency code for the transaction country — e.g. `"NGN"`
`description`	`string`	Yes	Description shown on the customer’s payment confirmation
`email_address`	`string`	Yes	Customer’s email address.
`first_name`	`string`	Yes	Customer’s first name
`last_name`	`string`	Yes	Customer’s last name
`redirect_url`	`string`	Yes	URL to redirect the customer to after successful payment
`cancel_url`	`string`	Yes	URL to redirect the customer to if they cancel
`error_url`	`string`	Yes	URL 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
}

{
  "message": "Transaction data found",
  "data": {
    "transaction_reference": "P-C-20260313-I840WFC6LS",
    "amount_received": 5.33,
    "transaction_fee": 0.33,
    "transaction_status": "Initialized",
    "sender_name": null,
    "sender_account_number": null,
    "source_bank_name": "NA",
    "initiated_date": "2026-03-13 15:13:10.521614",
    "current_status_date": null,
    "currency": "USD",
    "session_id": "TRN68681366586A",
    "merchant_transaction_reference": "TX213139dx",
    "transaction_type": "Apple Pay",
    "virtual_account_number": null,
    "status_reason": null
  },
  "success": true
}

{
  "message": "Transaction data found",
  "data": {
    "transaction_reference": "P-C-20260313-I840WFC6LS",
    "amount_received": 5.33,
    "transaction_fee": 0.33,
    "transaction_status": "Failed",
    "sender_name": null,
    "sender_account_number": null,
    "source_bank_name": "NA",
    "initiated_date": "2026-03-13 15:13:10.521614",
    "current_status_date": "2026-03-13 15:28:33.619368",
    "currency": "USD",
    "session_id": "TRN68681366586A",
    "merchant_transaction_reference": "TX213139dy",
    "transaction_type": "Apple Pay",
    "virtual_account_number": null,
    "status_reason": "Transaction status: CANCELLED"
  },
  "success": true
}

Errors

Error	Cause	Fix
`"Kindly check the provided Authorization"`	Invalid or missing API key	Re-encode your key and use the `Payaza <key>` format
`"Transaction Reference already exists"`	Reused `transaction_reference`	Generate a unique reference per payment attempt
`"Payment option can be either GOOGLEPAY or APPLEPAY"`	Invalid `payment_option` value	Pass exactly `"GOOGLEPAY"` or `"APPLEPAY"`
`"Payment option is currently not available via this channel"`	Unsupported currency code	Use a supported currency for wallet payments
`"Transaction not found"`	`transaction_reference` does not exist	Verify 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.

Get started

Developer tools

Accept payments

Send money

Disputes & refunds

Account management

Split Settlements

Overview

Key Requirements

Endpoints

How it works

Step 1 — Initiate the payment

Request parameters

Sample response

Step 2 — Query transaction status

Errors

What’s next

Card Collections

Webhooks

​Overview

​Key Requirements

​Endpoints

​How it works

​Step 1 — Initiate the payment

​Request parameters

​Sample response

​Step 2 — Query transaction status

​Errors

​What’s next

Card Collections

Webhooks

Overview

Key Requirements

Endpoints

How it works

Step 1 — Initiate the payment

Request parameters

Sample response

Step 2 — Query transaction status

Errors

What’s next