Skip to content

Payments

Operations related to creating and managing deposits and withdrawals

Operations

Create a deposit or a withdrawal

Request

Create a deposit or a withdrawal by using a single endpoint. The paymentType field determines the operation:

  • DEPOSIT — fund an account via Apple Pay, Google Pay, BLIK, CARD, ONRAMP, PAYID, or a European bank-redirect APM (iDEAL, Bancontact, Multibanco, EPS, Przelewy24).
  • WITHDRAWAL — send funds out via PAYID, SEPA, FPS or CARD.

Payment types & methods

Choose a paymentType, then a paymentMethod valid for that type:

paymentTypepaymentMethod
DEPOSIT (pay-in)APPLEPAY, GOOGLEPAY, BLIK, CARD, ONRAMP, PAYID, IDEAL, BANCONTACT, MULTIBANCO, EPS, P24
WITHDRAWAL (payout)PAYID, SEPA, FPS, CARD
DEPOSIT — onramp terminals onlyUSER_CHOICE, ONRAMP_PAYID, ONRAMP_PIX, ONRAMP_ZAR, ONRAMP_PSE, ONRAMP_KHIPU, ONRAMP_QRTHWALLET, ONRAMP_CARD, ONRAMP_INTERAC, ONRAMP_OPENBANKING, ONRAMP_GBPBANKTRANSFER, ONRAMP_SPEI, ONRAMP_APPLEPAY, ONRAMP_GOOGLEPAY

The last row applies only when your terminal is configured for onramp. USER_CHOICE lets the customer pick in the widget; an ONRAMP_* value pins the widget to that one method. See Onramp — deposit in the request selector.

When making an NFT purchase only the methods APPLEPAY, GOOGLEPAY, OPENBANKING, CARD are available. The request schema depends on paymentMethod.

Authentication

Every request needs an Authorization: Bearer <API_KEY> header and a Signature header — HMAC-SHA256 of the request body, keyed with your sign key. Ready-to-run samples in PHP, Node.js, Python and C# are in the request samples panel.

See Authentication for the full details, including why signatures get rejected and how to verify the ones we send you.

Security
Bearer and Signature
Bodyapplication/jsonrequired
One of:

Apple Pay deposit. The response returns a redirectUrl — send the customer there to complete the payment.

Required: paymentType, paymentMethod, amount, currency, reference, billingAddress, returnUrl, webhookUrl. To let the customer pick the method instead of fixing it here, send USER_CHOICE — see the Onramp entry.

paymentTypestring(PaymentType)required
Value:"DEPOSIT"
paymentMethodstringrequired
Value:"APPLEPAY"
amountnumber, (float), > 0required
currencystringrequired
additionalParametersobject(AdditionalParametersOnramp)

Method-specific parameters, plus the crypto destination for onramp terminals.

referencestring or nullrequired
billingAddressobject(BillingAddress)required

Billing address.

returnUrlstring or nullrequired
webhookUrlstring or nullrequired

URL to receive payment status updates. Interchangeable with callbackUrl — both perform the same function. At least one of webhookUrl or callbackUrl must be provided.

browserobject(Browser)

Browser information (commonly required for wallet-based methods).

curl -i -X POST \
  https://api.napoleonpay.com/api/v1/payments \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>' \
  -H 'Content-Type: application/json' \
  -H 'Signature: YOUR_API_KEY_HERE' \
  -d '{
    "paymentType": "DEPOSIT",
    "paymentMethod": "APPLEPAY",
    "amount": 20,
    "currency": "EUR",
    "reference": "YOUR-SYSTEM-TRX-ID",
    "billingAddress": {
      "countryCode": "LT"
    },
    "returnUrl": "https://example.com/return",
    "webhookUrl": "https://example.com/webhook"
  }'

Responses

Payment created successfully.

The payment is returned wrapped in a result object:

{ "result": { "id": "...", "paymentStatus": "PENDING", ... } }

For deposits (pay-ins) result includes a redirectUrl — redirect your customer there to complete the payment. For withdrawals (payouts) there is no redirectUrl.

The payment starts as PENDING; the final status (completed or failed) is delivered to your webhookUrl as a callback (see Callbacks below), not in this response. Note that webhook payloads are not wrapped in result — their fields are at the top level.

PAYID H2H deposits additionally return the PayID transfer details as top-level fields alongside result — number (the PayID address), full_holder_name, payment_description, amount, currency, uuid, order_id. Display these to your customer so they can complete the bank transfer; there is no redirect in this flow.

Bodyapplication/json
One of:

The created payment, wrapped in a result object. Deposits include a redirectUrl inside result (Redirect flow); withdrawals do not. For PAYID H2H deposits the response additionally carries the PayID transfer details as top-level fields next to result (number, full_holder_name, payment_description, …) — display these to your customer instead of redirecting.

resultobject(BasePaymentResponse)required
numberstring or null

PAYID H2H flow only. The PayID address (e.g. an email) your customer must send the transfer to. Display it together with payment_description and amount.

full_holder_namestring or null

PAYID H2H flow only. Account holder name of the receiving PayID — show it to the customer so they can verify the recipient.

payment_descriptionstring or null

PAYID H2H flow only. Payment reference code the customer must attach to the transfer.

amountstring or null

PAYID H2H flow only. Amount to transfer, formatted with two decimals.

currencystring or null

PAYID H2H flow only. Currency of the transfer.

uuidstring or null

PAYID H2H flow only. Unique identifier of this H2H payment instruction.

order_idstring or null

PAYID H2H flow only. Equals result.id — the NapoleonPay payment id.

Response
{
  "result": {
    "id": "01990efa-5437-70c6-8244-85546f382bb3",
    "paymentStatus": "PENDING",
    "created": { … },
    "paymentType": "DEPOSIT",
    "description": "Test ApplePay payment for order order-45c721ca",
    "paymentMethod": "APPLEPAY",
    "reference": "order-45c721ca",
    "amount": 10.23,
    "currency": "EUR",
    "customer": null,
    "billingAddress": { … },
    "redirectUrl": "https://gate.napoleonpay.io/payment/form/init/BB38447031435167306949777573304A3062422B4D486E55532F436B733679673758437038776C6A634243343D"
  }
}

Callbacks

Payment status update
post