Apple Pay payment

Direct Apple Pay Payment allows merchants to process Apple Pay transactions directly via a server-to-server connection. This integration enables merchants to handle the Apple Pay payment token securely on their backend without relying on the hosted checkout interface.

Use case A typical scenario involves collecting the Apple Pay token on the frontend (e.g., a website or mobile app) and securely transmitting it—along with the transaction session_id and amount—to this API.

This approach provides merchants with more control over their transaction flow, custom logic, and integration with internal systems while ensuring full PCI and Apple Pay compliance.

Setup

Before you can use the Submit Direct Apple Pay Payment API, ensure the following prerequisites are met:

1. Apple Pay integration is implemented on your frontend to collect the payment token.

2. A valid session_id is created using the Checkout API, which generates a unique session_id.

3. The merchant has a configured Payment Gateway pg_code supporting Apple Pay transactions.

4. The API must be accessed through HTTPS to ensure end-to-end encryption.

Authentication

This API uses Basic Authentication. For more details about basic authentication, please check here.

Permissions

The following permissions are required to use this API:

• Payment Processing: The user or service account must have permission to initiate payment requests.

• Session Access: The merchant must have valid access to the session_id created via the Checkout API.

• Gateway Access: The configured payment gateway must be active and support Apple Pay transactions.

How It Works

1. Frontend collection: The customer completes the checkout using Apple Pay on your website or mobile app. The frontend obtains a valid Apple Pay token containing encrypted payment data.

2. Server submission: Your backend sends a POST request to the Submit Direct Apple Pay Payment API, including:

   • payload: Structured token with encryption data and payment method details.

   • session_id: the transaction session identifier

   • amount: the payment amount

   • Optional: customer and address details

3. Gateway processing: Ottu forwards the transaction details to the configured payment gateway.

4. Response handling: The response returns the final payment details, including transaction state, paid amount, gateway response, and message status.

Use this response to update your order or transaction status.

API Schema Reference

Submit a direct Apple Pay payment (Merchant API)

post

Allows merchants to submit an Apple Pay payment directly via server-to-server integration. This endpoint requires private key authentication and expects a valid Apple Pay token structure in the request payload under payload.

Typical use case: The merchant collects the Apple Pay token on their frontend and sends it to this endpoint along with session and amount information.

Authorizations

basicAuth

AuthorizationstringRequired

Body

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

pg_codestring · nullableOptional

The unique pg_code used for this payment instrument.

session_idstringRequired

A unique identifier for the payment transaction (session).

Responses

200Success

application/json

amountstringRead-onlyRequired

Denotes the total sum of the payment transaction, which encompasses the cost of the procured items or services, excluding any supplementary fees or charges.

capture_delivery_addressbooleanOptional

By enabling this, you will ask for user's address. If enabled, capture delivery coordinates should also be active.

capture_delivery_locationbooleanOptional

By enabling this, you will ask for user's delivery location on a map.

currency_codestring · min: 3 · max: 3Required

The specified currency represents the denomination of the transaction.Nevertheless, it doesn't necessarily mandate payment in this exact currency.Due to potential currency conversions or exchanges, the final charge may be in a different currency.

customer_address_citystring · max: 40Optional

The city of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_countrystring · min: 2 · max: 2Required

The country of the customer's billing address, formatted as a two-letter ISO country code (e.g., 'US' for United States, 'CA' for Canada). This field may be used to send the billing address to the payment gateway.

customer_address_line1stringOptional

The first line of the customer's billing street address. This field may be used to send the billing address to the payment gateway.

customer_address_line2stringOptional

The second line of the customer's billing street address, if available. This field may be used to provide additional address information, such as an apartment or suite number.

customer_birthdatestring · nullableOptional

The customer's date of birth in ISO format (YYYY-MM-DD).

customer_address_postal_codestring · max: 12Optional

The postal code of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_address_statestring · max: 40Optional

The state or region of the customer's billing address. This field may be used to send the billing address to the payment gateway.

customer_emailstring · max: 128Optional

The email address of the customer that is used to send payment notifications and receipts, and can be used for fraud prevention. This field is mandatory and is always sent to the payment gateway. It may also be included in the invoice, receipt, email, and displayed on the payment page.

customer_first_namestring · max: 64Optional

The first name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_idstring · max: 64Optional

The customer ID is a unique identifier for the customer within the merchant's system. It is also used as a merchant identifier for the customer and plays a critical role in tokenization. All the customer's cards will be associated with this ID.

customer_last_namestring · max: 64Optional

The last name of the recipient of the payment. This field is used for various communications such as the invoice, receipt, email, SMS, or displayed on the payment page. It may also be sent to the payment gateway if necessary.

customer_phonestring · max: 32Optional

Customer phone number associated with the payment. This might be sent to the payment gateway and depending on the gateway, it may trigger a click to pay process on the payment page. The phone number will also be included in the invoice, receipt, email, and displayed on the payment page.

extraanyOptional

The extra information for the payment details, which the merchant has sent it in key value form.

feestringRead-onlyRequired

The fee denotes the sum the customer pays in their chosen payment currency. This may vary from the transaction's designated currency. The fee is computed once to maintain precision and uniformity throughout the payment procedure.

gateway_accountstringRead-onlyRequired

This code corresponds to the payment gateway and plays an essential role in facilitating payment transactions.

gateway_namestringRead-onlyRequired

The name of the payment gateway service being utilized.

is_sandboxbooleanOptional

Indicates whether the operation was performed in a test environment or not.

messagestringRead-onlyRequired

This represents the message, either transmitted by the Payment Gateway (PG) or established by Ottu, that provides a detailed illustration of the payment's current status.

order_nostring · max: 128 · nullableOptional

The unique identifier assigned to this payment transaction. It is used for tracking purposes and is set by the merchant or the system.

paid_amountone ofRead-onlyRequired

The paid amount encompasses fees or captured amounts from authorized transactions. This total is derived from the specified 'amount' field, converting foreign currencies to the default as necessary. This might result in minor variations due to fluctuations in exchange rates.

number · doubleOptional

or

stringOptional

payment_typestring · enumOptional

Type of payment. Choose one_off for payments that occur only once without future commitments. Choose auto_debit for payments that are automatically deducted, such as recurring subscriptions, installments, or unscheduled auto-debits.

Choose save_card if you want to perform a card tokenization operation.

NOTE: If auto_debit is selected:

1. agreement and customer_id parameters will also be mandatory.
2. Only PG codes supporting tokenization can be selected. As a side effect, the card used for the payment will be associated with the supplied agreement.id. This card will be locked, preventing the customer from deleting it from the system until an alternate card is chosen for auto-debit payments.

NOTE: If save_card is selected:

1. The amount must be zero for the save card operation.
2. The selected MID(pg_code) must support tokenization to enable the save card operation.
3. Please note that the save card operation is considered successful without any funds being charged.
4. Once a card is created, Ottu will send a webhook containing the card details to the merchant's webhook URL.
5. When the transaction type is save_card, all previously saved cards returned in the sdk_preload_payload should be hidden since the user is saving a new card and does not need to select from existing ones.

• one_off - One Off
• auto_debit - Auto Debit
• save_card - Save Card

Possible values:

reference_numberstringRead-onlyRequired

refunded_amountnumber · doubleOptional

The total refunded amount for the payment transaction.

remaining_amountnumber · doubleRead-onlyRequired

The residual amount due. Together with the editable amount, it indicates the outstanding balance of a transaction awaiting settlement.

resultstring · enumRead-onlyRequired

Indicates the outcome of the operation. success denotes a successful operation.

Possible values:

session_idstring · max: 128Optional

A unique identifier for each payment transaction, used to maintain the session state during the payment process.

settled_amountnumber · doubleRead-onlyRequired

The amount that has been paid or authorized in its original currency, excluding any fees.

signaturestringRead-onlyRequired

Signature Field: A cryptographic hash used to guarantee data integrity and authenticity during client-server exchanges. This hash ensures that the API payload has not been tampered with, and can only be verified by authorized parties.

statestringRead-onlyRequired

transaction_log_idinteger · max: 2147483647 · nullableOptional

Identifies the transaction log associated with the payment transaction. A transaction log is created for each record that is dispatched during a bulk dispatch process.

timestamp_utcstring · date-timeRead-onlyRequired

This field represents the timestamp at which ottu processed the transaction.While this often corresponds to the payment time,it's important to note that it might not always be the case.Payments can be acknowledged at a later time,so this timestamp might not align precisely with the actual payment time.

voided_amountnumber · doubleOptional

The total voided amount for the payment transaction.

400Error

application/json

401Error

application/json

post

/b/pbl/v2/payment/apple-pay/

HTTPcURLJavaScriptPython

POST /b/pbl/v2/payment/apple-pay/ HTTP/1.1
Host: sandbox.ottu.net
Authorization: Basic username:password
Content-Type: application/json
Accept: */*
Content-Length: 320

{
  "payload": {
    "paymentData": {
      "version": "text",
      "data": "text",
      "signature": "text",
      "header": {
        "ephemeralPublicKey": "text",
        "wrappedKey": "text",
        "publicKeyHash": "text",
        "transactionId": "text"
      }
    },
    "paymentMethod": {
      "displayName": "text",
      "network": "text",
      "type": "text"
    },
    "transactionIdentifier": "text"
  },
  "pg_code": null,
  "session_id": "text"
}

application/jsonapplication/x-www-form-urlencodedmultipart/form-data

{
  "pg_params": {
    "auth_code": null,
    "card_type": null,
    "card_holder": null,
    "cardholder_email": null,
    "card_expiry_month": null,
    "card_expiry_year": null,
    "full_card_expiry": null,
    "card_number": null,
    "card_issuer": null,
    "ref": null,
    "result": null,
    "track_id": null,
    "post_date": null,
    "transaction_id": null,
    "payment_id": null,
    "pg_message": null,
    "receipt_no": null,
    "transaction_no": null,
    "decision": null,
    "card_expiry": null,
    "card_details": null,
    "dcc_payer_amount": null,
    "dcc_payer_currency": null,
    "dcc_payer_exchange_rate": null,
    "rrn": null
  },
  "agreement": {
    "id": "text",
    "amount_variability": "fixed",
    "start_date": "2026-03-29",
    "expiry_date": "2026-03-29",
    "max_amount_per_cycle": "text",
    "cycle_interval_days": 1,
    "total_cycles": 1,
    "frequency": "irregular",
    "type": "recurring",
    "seller": {
      "name": "text",
      "short_name": "text",
      "category_code": "text"
    }
  },
  "amount": "text",
  "amount_details": {
    "currency_code": "text",
    "amount": "text",
    "total": "text",
    "fee": "text",
    "exchange_rate": "text"
  },
  "capture_delivery_address": true,
  "capture_delivery_location": true,
  "card_acceptance_criteria": {
    "min_expiry_time": 1
  },
  "currency_code": "text",
  "customer_address_city": "text",
  "customer_address_country": "text",
  "customer_address_line1": "text",
  "customer_address_line2": "text",
  "customer_birthdate": null,
  "customer_address_postal_code": "text",
  "customer_address_state": "text",
  "customer_email": "text",
  "customer_first_name": "text",
  "customer_id": "text",
  "customer_last_name": "text",
  "customer_phone": "text",
  "extra": null,
  "fee": "text",
  "gateway_account": "text",
  "gateway_name": "text",
  "gateway_response": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "initiator": {
    "id": 1,
    "first_name": "text",
    "last_name": "text",
    "username": "text",
    "email": "[e-mail]",
    "phone": "text"
  },
  "is_sandbox": true,
  "message": "text",
  "order_no": null,
  "paid_amount": 1,
  "payment_type": "one_off",
  "reference_number": "text",
  "refunded_amount": 1,
  "remaining_amount": 1,
  "result": "pending",
  "session_id": "text",
  "settled_amount": 1,
  "signature": "text",
  "state": "text",
  "token": {
    "brand": null,
    "customer_id": "text",
    "cvv_required": true,
    "expiry_month": "text",
    "expiry_year": "text",
    "is_expired": true,
    "is_preferred": true,
    "name_on_card": null,
    "number": null,
    "pg_code": "text",
    "pg_name": "knet",
    "token": "text",
    "agreements": null
  },
  "transaction_log_id": null,
  "timestamp_utc": "2026-03-29T23:22:10.061Z",
  "transactions": [
    {
      "amount": "text",
      "currency_code": "text",
      "order_no": null,
      "session_id": "text",
      "state": "paid"
    }
  ],
  "voided_amount": 1
}

Guide

Endpoint

POST /merchant/v1/applepay/direct-payment/

Headers

Key	Value
Content-Type	application/json
Authorization	Basic <base64(client_id:client_secret)>

---

Request Body Example

{
  "pg_code": "apple_pg_001",
  "session_id": "1f72ac4b-098b-4a65-8e29-0cc2023b22ef",
  "payload": {
    "data": "Encrypted Apple Pay token data",
    "signature": "MEQCID3e...",
    "header": {
      "ephemeralPublicKey": "MFkwEwYHKoZIzj0CAQYIKo...",
      "publicKeyHash": "uKxZ1l...",
      "transactionId": "b14b5a..."
    }
  },
  "amount": "100.00",
  "currency_code": "USD",
  "customer_email": "[e-mail]",
  "customer_first_name": "John",
  "customer_last_name": "Doe",
  "customer_id": "cust_10023",
  "payment_type": "one_off"
}

Successful Response Example

{
  "result": "success",
  "message": "Payment processed successfully",
  "pg_params": {
    "transaction_id": "tx_728193",
    "auth_code": "A7G93H",
    "status": "Approved"
  },
  "amount": "100.00",
  "currency_code": "USD",
  "paid_amount": "100.00",
  "timestamp_utc": "2025-10-08T14:33:12Z",
  "session_id": "1f72ac4b-098b-4a65-8e29-0cc2023b22ef",
  "state": "completed",
  "signature": "f1ab9d62e4c..."
}

Error Response Example

{
  "result": "failed",
  "message": "Invalid Apple Pay token",
  "state": "error"
}

• session_id must be generated through the Checkout API.

• The payload structure must strictly follow the Apple Pay Token format.

• The pg_code identifies the gateway account associated with this transaction.

• The API supports both sandbox and production modes depending on the merchant configuration.

Best Practices

1. Token Security: Always handle Apple Pay tokens securely. Process them immediately and avoid storing raw token data.

2. Validation: Verify that the session_id corresponds to a valid checkout session before submission.

3. Error Handling: Implement retry logic for network errors, but avoid retrying failed or declined transactions automatically.

4. Currency and Amount Consistency: Ensure the currency and amount match the values displayed to the customer during checkout to prevent mismatched payments.

5. Logging and Signature Verification: Log API responses and verify the signature field to ensure data integrity.

6. Test Thoroughly: Use sandbox mode for initial integration to confirm the Apple Pay token exchange and gateway communication work as expected.

FAQ

Q1: Can I use this API without the Checkout API? No. You must first create a transaction session via the Checkout API, which provides the session_id used here.

Q2: What happens if the Apple Pay token expires before submission? The payment will fail. Tokens should be submitted immediately after being generated by the Apple Pay sheet.

Q3: Is this API suitable for recurring or auto-debit payments? Yes. Use the payment_type as auto_debit, and ensure both agreement and customer_id are provided.

Q4: What is the difference between this API and the hosted checkout method? This API allows server-to-server processing, giving merchants more flexibility and control, while hosted checkout handles token submission via Ottu’s front-end interface.

Q5: How can I test this integration? Use sandbox credentials and test Apple Pay tokens to simulate different transaction outcomes before going live.