Payoneer Checkout

What you need

Payoneer Checkout portal → Integration → API access:

• merchant_id: the API username (merchant code). It is the same for all your stores.
• secret_key: the Payment token. Created with GENERATE TOKEN; live and test environments need separate tokens, and a token is shown only once.
• merchant_key: the Store code (the Store codes tab on the same page). Payoneer calls it division; every store has its own.

In your panel choose Settings → Payments → Add method → Payoneer Checkout and enter all three.

Sandbox: enter a token generated while the portal's environment switch is on test and tick sandbox (test) mode; the panel then talks to api.sandbox.oscato.com. Going live, flip the portal to live, generate a live token and untick the box (api.live.oscato.com).

The notification and return URLs are attached to every payment automatically; nothing has to be configured in the Payoneer portal. Their shape:

https://<your-panel-domain>/payments/payoneer/callback   (server notification)
https://<your-panel-domain>/payments/payoneer/return     (the customer's return)

The notification URL must be HTTPS and resolve to a public IP; while your domain is not yet pointed at us, a payment cannot start.

Flow

1. The customer enters an amount and picks Payoneer. A phone number is not required; it is sent when present.
2. The panel opens a LIST session at Payoneer (POST /api/lists, Basic auth with merchant code + payment token). Our payment reference goes into transactionId, the store code into division; the amount is sent in major units (100.50).
3. The customer is sent, full page, to Payoneer's hosted payment page (redirect.url, version v6); card entry, 3D Secure and wallets happen there, card data never touches your server.
4. When the payment finishes the customer comes back through returnUrl / cancelUrl. That return only redirects; it never credits balance.
5. At the same time Payoneer sends our server a notification (default: POST, JSON). The notification is not signed; the panel first checks the secret token it planted in the notification URL when opening the LIST (an HMAC under the payment token), then takes the longId from the notification and calls GET /api/charges/{longId} with its own credentials. Balance is credited only from the status in that response; the status and amount in the notification body are never used.
6. If identification.transactionId in the response is not our payment, the notification is ignored.

A second delivery with the same notificationId is ignored; balance is never credited twice. Every verified notification is answered with 200 OK. A notification with a missing or wrong token, or one that is neither payment nor session (customer, account), gets 400; Payoneer retries anything without a 2xx for 24 hours, which is harmless.

Statuses

Payoneer's status.code / status.reason pair maps as follows:

Payoneer	Panel
charged / debited, charged / closed	completed, balance credited
charged / fraud_suspected	on hold; complete it from Admin → Payments once Payoneer decides
preauthorized, pending	pending; when you capture the preauthorization, the resulting charged notification credits the balance
failed, declined, rejected, aborted, canceled	failed; resultInfo is written to the payment memo
expired (payment or session)	expired
paid_out, charged_back, information_requested	leaves a completed payment untouched; follow refunds and chargebacks in the Payoneer portal

For session notifications (entity=session) only expired / canceled / rejected / failed close the payment; listed and ended leave it pending.

Currencies

The panel starts the payment in the panel's currency and does not enforce a list. The transaction currencies Payoneer accepts are kept on the Supported currencies page of Payoneer's documentation; settlement to your Payoneer balance is in USD, EUR, GBP, HKD or JPY. In a currency Payoneer does not take, the LIST request is rejected with 422; the payment does not start and Payoneer's resultInfo message is raised as the error.

Customer fields

Payoneer requires country and a billing address the panel does not have. The country comes from the method's extra.country when set, otherwise it is derived from the panel currency (TRY → TR, EUR → DE, GBP → GB …, US for an unknown currency); it only steers which payment methods Payoneer offers. The billing address is a fixed placeholder (N/A, zip 00000); first and last name are derived from the username.

Common problems

• "Payoneer: kimlik doğrulama başarısız" (HTTP 401): wrong merchant code or payment token, or a test token used in live mode (or the reverse). Tokens are per environment.
• LIST rejected with 422 and a message about the division/store: the store code is wrong or belongs to another store. Copy it from API access → Store codes.
• Payment succeeded but no balance: look at the payment's memo under Admin → Payments. Confirm in the Payoneer portal → Store transactions that the transaction is charged/debited; if the notification could not be delivered, Payoneer retries for 24 hours. Make sure notifications are sent as POST (a GET notification is not accepted by the panel's callback URL).
• Card declined in sandbox: use Payoneer's test cards (4242 4242 4242 4242, any CVC, any future date); real cards do not work in the sandbox.