Payment outcomes, posted back to you

Three webhook URLs

There's nothing to register in a portal. You name the URLs in the body of each request, and every post carries your reference_id so you can match it to the request that started it.

• webhook_url gets the payment link and status callbacks. With transaction_flag=4 and linktopay_url=0, this is where the customer's payment link arrives.
• webhook_url_transaction gets the payment gateway's result. It's required for bank capture and bank out-payment.
• webhook_url_token gets the card token, if you send it.

If you don't want webhook outcomes at all, for example because you already take them from the payment gateway itself, talk to Paytia first.

Payment link webhook

Posted to webhook_url as application/json when linktopay_url=0, which is the default. Send linktopay_url=1 instead and the link comes back on the API response, with no webhook.

Transaction webhook

Posted to webhook_url_transaction as application/x-www-form-urlencoded, on one line. These are form fields, not JSON.

It comes in three shapes:

# 1. Authorise or direct payment, AVS matched
success=1&reference_id=&authcode=&AVSCV2=MATCHED&AddressResult=MATCHED&PostCodeResult=MATCHED&CV2Result=MATCHED

# 2. Tokenise or pre-auth
success=1&reference_id=&authcode=&token_id=&AVSCV2=MATCHED&AddressResult=MATCHED&PostCodeResult=MATCHED&CV2Result=MATCHED&token_expiry=YYYY-MM-DD

# 3. Authorise, no AVS match
success=1&reference_id=&authcode=&AVSCV2=NOTMATCHED&AddressResult=NOTMATCHED&PostCodeResult=NOTMATCHED&CV2Result=MATCHED

Exactly which fields arrive can vary by payment service provider. An aborted call posts custabort=1 or agentabort=1, both with success=0.

MOTO stage webhooks

On a phone payment you can get a webhook at every stage of the call, from agent verification through to card capture, so your own screen can follow along. This needs the sendCdrOnDetails v2 licence. Stage posts are form-encoded.

Dropped calls, rejected amounts and aborts arrive on these webhooks too. Exception handling →

Embedded checkout: postMessage events

These are separate from webhooks. When you embed the checkout or Agent Capture Assist frame (is_embedded_url=1), the iframe sends browser postMessage events to the page you name in iframeevent_url. That value must be the exact URL of the page hosting your listener, because an origin-only value receives nothing.

• resize-iframe carries iframeHeight, often fractional, so round it up.
• payment-status carries status (success, failed or error) plus card_brand, transaction_id, amount and customer_message.
• payment-method carries payment_type: card, google, paypal, bank, apple or empty.

window.addEventListener("message", (event) => {
  const ok = ["https://accounts.paytia.com",
              "https://accounts.pay729.net"];
  if (!ok.includes(event.origin)) return;
  const d = event.data;
  if (d?.type === "resize-iframe")
    iframe.style.height = Math.ceil(d.iframeHeight) + "px";
  if (d?.type === "payment-status") { /* d.status */ }
  if (d?.type === "payment-method") { /* d.payment_type */ }
});

Always check event.origin against Paytia's checkout hosts before you trust a message. Set payment_completionscreen=0 if you'd rather show your own completion screen than Paytia's.

Next

• Error codes on the API response →
• Exception handling →