Gateway APIs

A gateway REST API is a set of secure web endpoints that a merchant system calls to create payments, check status and issue refunds. Requests use HTTPS with an API key or OAuth token in the authorization header, and responses return JSON, which is a structured text format that programs can read easily. A typical base address looks like https://api.examplegateway.com/v1, and each operation has its own path, such as POST /v1/payments for creating a payment, GET /v1/payments/{payment_id} for checking status, and POST /v1/payments/{payment_id}/refunds for refunding it. The gateway validates the API key, the request format and the merchant account before it processes anything, and returns a clear error code when a required field is missing. Payment initiation is the first call, and it carries everything the gateway needs to authorize the transaction. A request includes merchant_id, order_id, amount, currency, payment_method, card token or card details, customer email, billing address and a return URL for redirect flows. For example, a request for order ORD-78412 might carry amount 499900, which represents 4,999 rupees in paise, currency INR, payment_method card, and card token tok_8f3k2m9q. The gateway responds with a payment_id such as pay_N8d2kL4m, a status such as authorized or failed, an authorization code, and a redirect URL when 3D Secure authentication is required. The merchant stores the payment_id and maps it to the order, because every later call uses that identifier. A status check lets the merchant confirm what really happened, even when the customer closes the browser or the network drops. The merchant calls GET /v1/payments/pay_N8d2kL4m and receives the current status, which may be created, authorized, captured, failed, refunded or partially refunded, plus the amount captured, the amount refunded, the acquirer reference number, and the time of the last update. This call is essential after a timeout, because the customer may have been charged even though the checkout page showed an error. A robust merchant system polls the status endpoint or waits for a webhook, and never ships goods on the basis of a browser redirect alone, since a redirect can be faked or interrupted. The refund API returns money to the customer, in full or in part, and it must be handled with the same care as a payment. A refund request includes the payment_id, the refund amount in the smallest currency unit, a refund reason such as duplicate charge or product returned, and a unique refund reference. The gateway checks that the refund amount does not exceed the captured amount, sends the refund to the acquirer, and returns a refund_id such as rfd_7Qw2xP9z and a status of processed or pending. A refund of 1,200 rupees against a 4,999 rupee order leaves a remaining refundable balance of 3,799 rupees. The customer usually sees the credit in three to five working days, depending on the issuing bank. Idempotency keys are the safety net that stops duplicate charges when a request is retried. The merchant generates a unique key for each logical operation, for example idem_ORD-78412_01, and sends it in a header called Idempotency-Key with the original request. If the network fails and the merchant resends the same request with the same key, the gateway recognizes the key and returns the original response instead of creating a second payment. If the merchant sends a different key, the gateway treats it as a new payment. This matters most during retries, timeouts and failover, where the same payment can be attempted twice through no fault of the customer, and the key is what keeps one order from becoming two charges.