Getting started with the Paytia API

Before you start

In the Paytia merchant portal, create an API key with Single JSON format selected. Each Paytia account you use gets its own X-API-KEY value. The knowledge base walks through it: how to add an API key.

A working integration has to handle five things:

Pulling data out of your application and mapping it to the Paytia fields.
A webhook URL that receives status updates from Paytia.
A redirect URL that hands the user back to your application from the Paytia screen.
Exception scenarios, such as a rejected amount or a dropped call.
Both the positive and the negative outcome of every flow.

Hosts

Both live hosts are production and neither takes a port. There's no separate sandbox domain: a live account can still run its payment gateway in test mode.

https://accounts.paytia.com
https://accounts.pay729.net

White-label accounts use https://{subdomain}.paytia.com for /api/subscription.

Endpoints

Every /api/* call sends X-API-KEY. Paytia accepts form-data on four endpoints:

Endpoint	Use it to
POST /api/payment_service	Process a payment or card capture. Most flows live here.
POST /api/subscription	Update or cancel a recurring payment plan.
POST /api/payment_update	Take or complete a two-stage payment.
POST /api/authorize	Mint an ACCESS-TOKEN (Enhance Security only).

Your first request

The smallest useful call: an immediate card payment taken over the phone, with the Agent Capture Assist screen URL returned to you. Replace YOUR_API_KEY and point webhook_url at an endpoint you control.

curl --request POST \
  'https://accounts.paytia.com/api/payment_service' \
  --header 'X-API-KEY: YOUR_API_KEY' \
  --form 'reference_id="ORDER-1001"' \
  --form 'amount="20.00"' \
  --form 'agent_id="101"' \
  --form 'firstname="Jane"' \
  --form 'lastname="Smith"' \
  --form 'countrycode="GB"' \
  --form 'webhook_url="https://your-app.example/paytia"' \
  --form 'web_agent_form="1"' \
  --form 'transaction_flag="0"'

bash

reference_id has to be new on every attempt. Send one Paytia has already seen and you get 208 Reference ID Already Exist. agent_id is required on flags 0 to 3, and on flag 4 when the agent licence is active.

What comes back

A success response is flat JSON:

{
  "url": "https://accounts.paytia.com/thirdparty/embededurl/MzIz/MjEzMjEzMQ==",
  "reference_id": "2132131",
  "status_code": 200
}

json

url is the Agent Capture Assist screen. It's a plain URL, not an iframe, so open it however suits your interface: embedded in an iframe, in a popup, in a new tab or as a redirect. Always read the body as well as the HTTP status, because a duplicate reference comes back as 208 with httpStatus: false. Error codes →

The transaction flag

One endpoint covers every flow. transaction_flag picks the operation Paytia runs against your gateway:

Flag	Behaviour	What it does
0	Immediate charge	Charge the full amount now.
1	Capture, tokenisation only	Capture card details and return a token. No charge, so send amount=0.00.
2	Pre-auth + immediate	Charge amount now and reserve reserve_amount.
3	Pre-auth only	Reserve reserve_amount on the card and return a transaction token.
4	Link to Pay	Generate a payment link, QR code or SMS.
5	Recurring	Subscription or plan-based recurring charge.
6	Reserved	Not in use.
7	Rolling reserve	Stripe-specific rolling reserve handling.
8	Web Checkout	Hosted checkout with products and shipping. Use with web_agent_form=2.
9	Bank out-payment	Pay out to a bank account (Acquired.com) with mode=bank.

Each flow page lists the fields that flow expects:

Outcomes arrive by webhook

The response only tells you the request was accepted. What happened to the payment reaches you later, posted to webhook_url and webhook_url_transaction. Webhook reference →

Need a hand?

Your Paytia account manager can help, or write to techsupport@paytia.com with the request you sent and the response you got. Not a customer yet? Ask about API access →

Your first Paytia request