Home > Shopify Tutorials > Shopify Payment Gateway API

What Is Shopify Payment Gateway API? How To Build a Shopify Payment Gateway

Last updated: October 01, 2023
This article has been written and researched by our expert Avada through a precise methodology. Learn more about our methodology





Payment Gateway is known as a technological product of E-commerce as Shopify to accept the debit as well as credit from all transactions. Shopify store owners always concern about how the Payment Gateway effective and convenient for their shoppers. There are a lot of Payment Gateways that online sellers can choose to customize the best choices for their shops. In addition, because of the differences in functionalities, shop owners should use different APIs depending on their purposes.

Among many choices, the store owners have an available Shopify payment in their shops. Besides, the Shopify Payments API allows the users to access information about their Shopify Payments account. It is easy for them to do that just by using the following resources such as Payouts, Dispute, Balance, or Transactions.

This article about Shopify Payment Gateway Api brings online sellers the definition and an overview of different API resources and reponses. It is easy for any store owners to build their Shopify Payments Gateway API on their own.

Related Posts:

What is Payment Gateway API?

Considered as a service that provides the users with automatic support for transactions, Payment Gateway API helps the shop owners to transfer payment from customers. After the sellers order a product in the online shop, the Payment Gateway API will perform several tasks such as Encryption, Authorization Request, Confirming the Order.

In detail, Encryption helps send the transaction data to the payment processor via the web browser server. The Authorization Request will send a card with the transaction data by two authorization requests such as approves or denies. Furthermore, the Confirming the Order task which allows the users to forward an authorization to the Payment Gateway. Since the gateway receives the message, they will respond back to their merchant.

payment gateway

Why is Payment Gateway API important?

In the payment process with multiple customers, it is necessary for the shop owners to vary their payment methods by adding different categories of Payment Gateway. This Payment Gateway API is such an important way for the online merchants to customize the customer’s details, product information. From delivering these requests including the signature value in the API from the store owners, it helps the users to verify credit card, debit card, etc if there is a third-party supporting the transaction processing. Therefore, the Payment Gateway API is an effective tool for any store to optimize its payment process.

Why is Payment Gateway API important

How to Build a Shopify payment gateway?

One of the most simple ways to Build a Shopify payment gateway is integrating the hosted payment page with Shopify’s checkout by using the Hosted Payment SDK. This Hosted Payment SDK allows the Shopify store owners to use a full-page redirect when finishing the checking out. Furthermore, this tool also strengthens all third-party payment gateway’s appearance with a standardized interface.

Because of the limitation of accessing to the Hosted Payment SDK, the online sellers need to ensure totally about their access. If they want to request access, they will need to fill into the Shopify Hosted Payment SDK Request Form before receiving the Shopify’s team approval. Within 30 days, if there is no response from them, the request for integration will be rejected. On the other hand, they will provide the necessary documentation required to contribute a payment gateway.

Build a Shopify payment gateway

Shopify Payment Gateway API resources and responses

As one of the default payment methods in Shopify, Shopify Payment Gateway is the tool to support all online shoppers in multiple ways such as credit cards, bank accounts or Paypal accounts. The Shopify Payments API allows you to access information about a merchant’s Shopify Payments account using the following resources.

Shopify Payment Gateway APIs

By the Shopify Payment Gateway API, it is easy for them to integrate credit cards into Shopify’s stores, shopping carts, and billing systems. To finish the payment of the purchase, the store owners enable using the Payment resource. Firstly, after the sellers submit their card details such as numbers, addresses so that they can create a session ID, which is used to create a payment. There are many Payment resources, but not all of them are compatible with direct payment gateways. Among a list of different payment resources below, the online sellers can choose the best one for their online shops.

Shopify Payments payouts

Payouts helps the users to know more about the money flows. By this function, they will track their money easily between their Shopify Payments account and the third-party bank account.

The Payouts properties can be listed down such as

  • id: an array of a unique number of the payout
  • status: it represents the transfer status such as
    • scheduled: The transactions are assigned after payouts are created, but they have not submitted to the bank yet.
    • in_transit: The payouts are in the processing to be considered by the banks.
    • paid: It informs that the payouts are successfully deposited into the bank.
    • failed: The third-party banks rejected the payouts.
    • canceled: Shopify canceled the payout.
  • date: the day that payouts are issued is written in ISO 8061 format
  • currency: the code of the payouts currency is in the ISO 4217
  • amount: this number lets the users know about the total amount of the payout.

Shopify Payments disputes

When the shop owners accept credit cards in charging their products, there are many cases that cardholders have issues with their credit cards so that they want to dispute their purchases with the banks. At that time, the banks can make a chargeback or inquiry.

Disputes occur for any Shopify shop so the sellers should know about their properties such as:

  • id: an array of a unique number of the payout
  • order_id: a unique ID of the dispute order.
  • type: Different values of the dispute when the order’s status is from in the inquiry phase into a chargeback.
    • inquiry: It is in the inquiry process.
    • in_transit: the payouts are in the processing to be considered by the banks.
    • chargeback: This value means that the dispute has been to be a chargeback.
  • currency: the code of the disputed amount is in the ISO 4217
  • amount: this number lets the users know about the total amount of the payout.
  • reason: There are many reasons for the dispute is not supported by the bank such as:
    • bank_not_process: The charge is not processed by the customer’s bank.
    • credit_not_processed: The merchant has sent refunds or credits for customers when they want to return products or cancel the transactions.
    • customer_initiated: The problems from the customer initiation for the dispute.
    • debit_not_authorized: Because the dispute has not been authorized, the bank cannot proceed with the debit.
    • duplicate: The same product was charged more than once claimed by customers.
    • fraudulent: The card users claim that they did charge for the payment.
    • general: The lack of details in the uncategorized dispute, so it is necessary for the online sellers to ask their customers to add more details.
    • incorrect_account_details: The information about their purchase is not correct.
    • product_not_received: In case the purchased products are not sent to customers.
    • product_unacceptable: The received products are defective, damaged, or different from the description.
    • subscription_canceled: After the customers cancel the order, the online sellers kept charging them.
    • unrecognized: The customers claim that they do not recognize the purchases.
  • network_reason_code: The reasons came from the cardholder’s bank.
  • status: In the Shopify, there are multiple values of the dispute as following: -needs_response: It is necessary to submit the evidence.
    • under_review: The cardholder’s bank is reviewing the submitted evidence.
    • charge_refunded: The inquiry amount of payment has been refunded by the merchants.
    • accepted: The dispute is accepted by merchants.
    • won: The bank decided following the merchant’s favor.
    • lost: The bank decided following the customer’s favor.
  • evidence_due_by: The last day that for evidence will be submitted.
  • evidence_sent_on: The day that the evidence was sent. If the evidence has not sent, online merchants can return null.
  • finalized_on: The day that the dispute was resolved. If the evidence has not resolved, online merchants can return null.

Shopify Payments account

The detail of these versions of the actions with the Shopify API allows users to know about the balance. The information about the current balance which is the amount not included in a Payout.

Shopify Payments account

Payments balance transactions

The movement of cash flow in Shopify stores will be recorded in detail in this section. The Balance Transactions is considered as a ledger for a Shopify Payments account. The Payouts properties can be listed down such as

  • id: an array of a unique number of of the transaction
  • type: it represents the different types of balance transaction such as: charge, refund, dispute, reserve, adjustment, credit, debit, payout, payout_failure, payout_cancellation.
  • test: The test modes when there is an Order or payment.
  • currency: the code of the payouts currency is in the ISO 4217
  • payout_id: The code of id for the paid payout of the transaction.
  • payout_status: If the transaction has not been included in a payout yet, the status of the payouts will represent as paid out or pended.
  • amount: The numbers will explain the gross amount of the transaction.
  • fee: The fees will be deducted from the transaction automatically.
  • net: The numbers explain the amount of the transaction.
  • source_id: The ID of the leading resources to the transaction.
  • source_type: The types of the resource include charge, refund, dispute, reserve, adjustment,payout
  • source_order_transaction_id: The ID of transaction which has this balance transaction
  • source_order_id: The id of the original Order results in this transaction.
  • processed_at: The time that the banks process the transaction.

Payments balance transactions

Versioning of the Shopify Payments API

Among the multiple Shopify Payments API, The REST APIs known as one of the most complex technologies is an architectural approach to communicate in web services development. The REST used by browsers can be thought of as the language of the internet. With cloud use on the rise, APIs are emerging to expose web services. REST is a great choice for building APIs that allow users to connect and interact with cloud services.

Through a MIME type, it offers schema versioning in the Accept header. The initial type is application/vnd.shopifypayments.v1+json. By default, all JSON requests receive the most recent version of the API. The client should specify the required version in the Accept header. A new version will be introduced only for non-backward compatible changes. For example, adding new properties is considered backward compatible and will not introduce a new version.

Pagination of Shopify Payments API responses

Requests that return an item collection are paginated. A Link header containing one or more hypermedia link relations for traversing pages will be included in every collection response. It’s recommended that clients use these provided URLs for traversing collections and do not construct their own, since the parameters are subject to change.

The property of the Shopify API has rel value :

  • next: The link to the next page immediately.
  • prev: The link to the previous page immediately.


For online merchants, the Shopify Payment API plays an important role in contributing their site because the API is such a proper way to write a program requesting services. It supports both the operating system and other applications, which maximize the efficiency of Shopify stores.

Hope our article on What is Shopify Payment Gateway API? will provide you with necessary information about Shopify Payment API. If you have any questions, feel free to leave it in the comment box below.

Mike is a content writer at Avada, with a love for video games, gadgets, and software. He has been writing about the industry now for over 7 years. He likes to keep up-to-date with the latest software releases. He's also an avid reader, and he enjoys spending time outdoors with family and friends. When he's not working, you can usually find him playing video games or exploring new outdoor activities.

Stay in the know

Get special offers on the latest news from AVADA.