> ## Documentation Index
> Fetch the complete documentation index at: https://docs.payaza.africa/llms.txt
> Use this file to discover all available pages before exploring further.

# Apple Pay & Google Pay

> Accept wallet payments from customers using Apple Pay and Google Pay. Initiate the payment server-side and confirm the outcome via webhook or status query.

## 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.

<Note>
  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.
</Note>

***

## Key Requirements

<Info>
  Use your **public API key** encoded in Base64 for all wallet payment requests.
  See the [Authentication guide](/guides/authentication) for setup instructions.
</Info>

Set these headers on every request:

```json theme={null}
{
  "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](/guides/webhooks) 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

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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>
</Steps>

***

## Step 1 — Initiate the payment

<CodeGroup>
  ```bash cURL — Apple Pay theme={null}
  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"
    }'
  ```

  ```bash cURL — Google Pay theme={null}
  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"
    }'
  ```
</CodeGroup>

### 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

```json theme={null}
{
  "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.

```bash cURL theme={null}
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>'
```

<CodeGroup>
  ```json Successful theme={null}
  {
    "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
  }
  ```

  ```json Initialized theme={null}
  {
    "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
  }
  ```

  ```json Failed theme={null}
  {
    "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
  }
  ```
</CodeGroup>

***

## 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](/guides/errors) for more detail.

***

## What's next

<CardGroup cols={2}>
  <Card title="Card Collections" icon="credit-card" href="/guides/card-collection">
    Accept card payments directly via the API.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/guides/webhooks">
    Receive real-time payment notifications from Payaza.
  </Card>
</CardGroup>