Skip to main content

Native Payments

Use Native Payments when you want full control of the client experience (web or mobile) and prefer not to use the Checkout SDK. Your client or backend collects a payment payload and sends it to Ottu to process the payment for a given session_id.

A payment payload can be:

  • Wallet payment data (e.g., Apple Pay paymentData, Google Pay paymentMethodData) — typically encrypted by the wallet.
  • Gateway token / network token (card-on-file or one-click use cases) — not necessarily encrypted.

Ottu processes the payload with the configured gateway and returns a normalized callback result.

Boost Your Integration

Ottu offers SDKs and tools to speed up your integration. See Getting Started for all available options.

When to Use​

  • Apple Pay or Google Pay buttons are rendered and managed by you.
  • Existing tokenization has already been implemented and needs to be used to charge with a gateway token.
  • Granular, SDK-less control of the UX is required, while Ottu's orchestration and gateway integrations are still leveraged.

Setup​

  • A valid session_id obtained from the Checkout API.
  • A Merchant Gateway ID (MID) with the payment service activated and properly configured in Ottu.

If multiple gateways are configured, always include the pg_code corresponding to the MID that has the target payment service enabled.
Example:
If a transaction has knet and mpgs pg_code but only knet supports Apple Pay, you must send
pg_code: knet when calling the Apple Pay endpoint.

Checklist​

  • Created a valid session_id.
  • Completed Apple Pay / Google Pay setup (if applicable).
  • Selected the correct invocation model (client or backend).
  • Used the appropriate API key type (Public API Key vs. Private API Key).
  • Sent wallet payment payload or gateway token (no raw card data).
  • Implemented backend sync logic.

Guide​

Workflow​

Client → Ottu​

  1. The client collects the wallet or tokenized payment payload and calls the Native Payments endpoint directly.
  2. The client receives the API callback response.
Never expose private keys on the client side

Never embed Private API Keys in client-side code — they grant full API access and will be compromised if exposed. Use a Public API Key for client-side calls.

If the call is made from the client side, the backend must be synchronized with the payment result by ensuring that one of the following actions is performed:

  • The API response is forwarded to the backend, or
  • The Payment Status Query API is called by the backend after the client confirms that the payment has been completed.

Client → Backend → Ottu (Recommended)​

  1. The client sends the payment payload to the backend.
  2. The backend calls the Ottu Native Payments endpoint.
  3. The backend receives the payment response callback.
  4. The backend processes the callback response and notifies the client side with the payment status.

Step-by-Step​

curl -X POST "https://sandbox.ottu.net/b/pbl/v2/payment/apple-pay/" \
  -H "Authorization: Api-Key your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "your_session_id",
    "pg_code": "apple-pay-gateway",
    "payload": {
      "paymentData": {
        "data": "base64_encrypted_payment_data...",
        "signature": "base64_signature...",
        "header": {
          "publicKeyHash": "hash...",
          "ephemeralPublicKey": "key..."
        },
        "version": "EC_v1"
      },
      "paymentMethod": {
        "displayName": "Visa 5766",
        "network": "Visa",
        "type": "debit"
      },
      "transactionIdentifier": "transaction_id..."
    }
  }'

Response (all endpoints return the same structure):

{
  "result": "success",
  "message": "successful payment",
  "pg_response": {}
}

Use the response values to reconcile the payment in your backend and update your order state.

Use Cases​

The general Setup prerequisites and checklist apply to all providers below.

danger

Never modify wallet payloads (Apple Pay, Google Pay) — any change invalidates token decryption. Always include pg_code if multiple gateways are configured.

  1. Configure Apple Pay on the client side (iOS / web).
  2. Collect the encrypted paymentData object from Apple Pay.
  3. Send the payload with the session_id to POST /b/pbl/v2/payment/apple-pay/.
  4. Ottu processes via the configured Apple Pay gateway and returns a unified result (succeeded, failed).

API Reference​

Select the payment provider to see its full interactive API schema:

Native Payment API(Apple Pay)​

Native Payment API(Apple Pay)

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

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.

Permissions​

Auth MethodRequired Permissions
API KeyAll permissions (admin access)
Basic AuthCan add payment requests or Can add e-commerce payments

Request​

Responses​

Last updated on

FAQ​

What's Next?​

Last updated on