Start a project
Start a project Book a call
International

Connecting delivery companies and payment gateways to your store: an API checklist

A checklist for Gulf and Iraq store owners who connect a courier or payment gateway: keys, webhooks, duplicates, statuses, cash on delivery, three-decimal currencies and a test list.

ESTASOFT
12 min read
Navy cover with a green hub circle linked to four white circles, with the title Connect couriers and payments
On this page
    On this page

      A courier or a payment gateway usually arrives as a plugin and a set of keys. Then a customer is charged twice, one order gets two waybills, a shipping rate fails at checkout, or a courier status means nothing to your team. Most faults trace back to questions nobody asked before the build.

      This guide is for owners of Shopify stores in the Gulf and Iraq who brief or approve this work. It explains how the three main connections differ, what to ask about keys, retries, duplicates, statuses and cash on delivery, and ends with a test list. Vendor facts come from pages read on 4 November 2026 and can change. The ERP side is covered in our guide to connecting Shopify to your ERP.

      Three connections with three sets of rules

      • Rates at checkout. A carrier service is a web address that Shopify calls with the cart and destination, and it replies with prices. Shopify's developer page says there is no retry: a timeout or an error means Shopify shows backup rates instead. The timeouts depend on traffic, from 10 seconds down to 3 seconds, and may change. Plans matter. Shopify's help page on carrier-calculated shipping lists Advanced and Plus, and Grow stores can add it for a monthly fee or by switching to annual billing. The developer page says creating a carrier service fails unless the store is on Advanced or higher, is on yearly billing or has the feature added for a monthly fee, or is a development store not on Basic. Plans change, so confirm yours with Shopify.
      • Labels, tracking and delivery status. After an order, your system or the courier's app can create a fulfillment with a tracking number, and delivery events can then be added. Shopify's help page on shipping carriers lists label carriers by country, and none of those countries is in the Gulf or Iraq, so ask each courier whether it has a Shopify app or connector, or whether you need custom work. Our page on integrations and APIs describes that kind of work.
      • Payments. Shopify's help page on Shopify Payments, read on 4 November 2026, lists the United Arab Emirates and none of Saudi Arabia, Qatar, Kuwait, Bahrain, Oman or Iraq, so check the current list. It says a store in an unlisted country needs a third-party provider. Shopify describes direct providers, where the customer stays on your store, and external ones, where the customer pays on a page hosted elsewhere. It says third-party transaction fees apply and gives no rate, so ask for the total cost. Its review page says the payments platform is invitation only and a Partner must be approved first. So ask a gateway first: does it already have a Shopify payment app, and who maintains it? For Iraq and Kurdistan, see our guide to online payments.

      Keys, sandbox and who owns the account

      Ask for test and live keys, and keep them apart. The gateway Tap, for example, lists on its developer page a test and a live secret key and public key, says test keys work in its sandbox, and warns that secret keys belong in the backend, not the browser.

      Aramex's developer page lists four APIs (rates, shipping, tracking and locations), says you need a valid username and account, and says to contact your Aramex representative to set one up. It does not mention a test environment. Ask the courier whether a test account exists, and for its current technical manual, before the build starts.

      The account is a contract between your company and the courier or gateway. The developer is only a user. Agree in writing that the account and every key are registered to your company, that keys live in a password manager and never in email or theme code, and that keys are replaced when a developer leaves.

      Shopify changes too. It releases an API version every three months and supports each for at least 12 months. A call to a retired version is answered by the oldest version still available, so old code can behave differently without an error. Ask who checks the version your integration uses.

      Webhooks, retries and duplicate messages

      A webhook is a message one system sends another when something happens. Shopify's page says your endpoint should answer 200 OK within five seconds. After no answer or an error, Shopify retries eight times over four hours, and a subscription created through the Admin API is deleted after eight consecutive failures. The same message can arrive twice, so Shopify tells apps to skip repeats using the webhook ID header, and suggests a periodic job that fetches data they may have missed. Each delivery carries a signature header that the app should verify.

      Tap's webhook page shows a signature header and how to check it, but not its retries or the reply it expects. Ask each provider how many retries it makes, what reply it expects and whether you can replay a missed event. Then ask your developer what happens when a message never arrives. The right answer is a scheduled check that compares the provider's records with your orders.

      Idempotency: charge once, ship once

      Idempotency means that sending the same request twice has the same result as sending it once. It protects you when a network drops and the system retries. Shopify's page on payments processing tells payment apps to implement idempotency and a retry policy.

      One gateway, Checkout.com, shows how it can work on a page last updated 19 August 2026. You send a unique key in the Cko-Idempotency-Key header. If the first request succeeded, a repeat gets the same response. Keys expire after 72 hours by default. A duplicate that arrives while the first is still running gets a 409 Conflict. Ask your gateway for the same facts in writing.

      Couriers need the same care. If a create-shipment call times out and the system retries, do you get two waybills? The Aramex developer page we read does not say, so ask each courier whether a repeated shipment with the same reference is refused.

      Statuses and order mapping

      A cash on delivery order in Shopify is unpaid and shows as Pending, and Shopify's order status page names manual methods such as cash on delivery among the cases for that status. Courier statuses need a map to words your team understands. Shopify's fulfillment event statuses (Admin GraphQL API version 2026-10) are eleven: attempted delivery, carrier picked up, confirmed, delayed, delivered, failure, in transit, label printed, label purchased, out for delivery and ready for pickup. None covers a parcel returned to the sender, so decide where that status will live, for example in an order tag.

      Ask the courier for its full list of status and error codes. Keep a shared list with three columns: the courier's code, what Shopify shows, and what your team does. Send unknown codes to a review list and alert a person. Shopify's fulfillmentCreate page says that leaving out line items fulfills every item in the fulfillment order, which matters for split shipments.

      Cash on delivery and three-decimal currencies

      Shopify's help page treats cash on delivery as a manual payment method: the order stays unpaid until you mark it paid. Aramex's UAE FAQ has a short cash on delivery answer saying merchants can use Aramex to deliver and collect payment from buyers, and it does not show when the cash reaches you or what it costs. The integration has two jobs. It must send the right amount to collect, which is the unpaid balance after discounts, shipping and any cash fee you charge. And it must send no amount for orders that are already paid. Test both, because a wrong flag means a customer asked to pay twice. Matching the cash later is the subject of our guide to cash on delivery reconciliation, and the Iraq details are in our guide to selling in Iraq.

      Currency decimals are a second trap. The ISO 4217 list kept by SIX, published 17 September 2026, shows the Kuwaiti dinar, Bahraini dinar, Omani rial and Iraqi dinar with three minor units, and the UAE dirham, Saudi riyal and Qatari rial with two. Tap's webhook page says amounts are rounded to the currency's standard decimals, with SAR at two and BHD at three. Shopify's carrier service page says a rate's total price is given in subunits. Test with a real cart in KWD, BHD or OMR: the rate, the cash amount on the waybill and the gateway amount should match the order to the last digit.

      Failure cases to test before go-live

      Ask for a written test plan, with a screenshot or log for each result.

      1. The courier service is slow or down at checkout. The customer sees a backup rate you have agreed.
      2. A payment succeeds but the customer closes the browser before returning. The order is still paid once.
      3. A payment fails and the customer tries again. There is one order and one charge.
      4. The same webhook arrives twice. Nothing is created or sent twice.
      5. A webhook never arrives. The scheduled check finds the order.
      6. The courier rejects an address, for example one in Arabic, with a missing city or a phone number without a country code. A person gets a clear message. Our guide to checkout design for Gulf shoppers covers how to collect these fields.
      7. One order ships as two parcels. Each has its own waybill and tracking number.
      8. A cash order and a prepaid order, each with a discount and a three-decimal currency. All amounts match.
      9. An order is cancelled or refunded after dispatch. The courier is told, and the order shows it.
      10. A key expires or is replaced. Someone gets an alert, and the live store keeps working.

      Questions to put to a courier or a gateway

      • Which countries, cities and payment methods are covered, and which need separate approval?
      • Do you accept Arabic and English names and addresses, and what appears on the label?
      • For cash on delivery: how often, by what method and with what statement do you pay me, and what do you deduct?
      • When the contract ends, can I export my history and cancel keys the same day?

      Ask your developer to log each request and reply with the order number, time and result, and to keep secret keys out of the logs. Logs hold names, phone numbers and addresses, so ask a local adviser which data protection rules apply.

      This is general information, not legal or tax advice. Check the current rules or ask a qualified adviser before you decide.

      If you want a courier or gateway connected with these checks in place, ESTASOFT can help with integrations and APIs. Send a short brief on the contact page.

      Sources

      Written by
      ESTASOFT

      Need help with a project?

      Share a short brief. We reply with next steps.

      Start a project Book a call

      Book a call

      30 minutes. Free.

      Tell us about your project and we will suggest a time.

      Send a request

      Or email us at info@estasoft.com

      Cookie preferences

      Necessary

      Needed for the site to work. Always on.

      Always on

      Preferences

      Remember choices such as language and region.

      Analytics

      Help us understand which pages are useful.

      Marketing

      Used to measure and improve campaigns.