Introduction

G2APay provides several payment methods – such as credit cards, PayPal or payment by means of the G2A wallet. You can quickly activate them in your e-commerce system.

This documentation features the possible methods of implementing on-line payments with G2APay. The first part introduces the payment service whereas the second one presents possible ways of integration.

Payment flow

A payment is processed via G2APay in two steps:

  • The buyer places an order on the merchant e-commerce application.
  • G2APay process payment and confirm that the payment is settled correctly.
Payment flow schema
  1. In the merchant's shopping cart the Buyer uses the G2APay button to start off the payment.
  2. In the G2APay Checkout the user selects a payment method, provides the details and finalizes the payment.
  3. G2APay Checkout redirect user to merchant's order summary page with appropriate payment status.

Payment status

The diagram below shows how the payment status changes during the entire process.

Payment flow schema

Please note that:

  1. While starting payment in G2APay Checkout it has NEW status.
  2. Status PENDING is not notified by IPN (Instant Payment Notification) – payment is in this state immediately after returning from G2APay Checkout.
  3. Every status is notified by an IPN.
  4. Refunds can be triggered manually using REST API, but the confirmation (a change of status) will be notified by IPN.

Possible transaction status:

  • PENDING – the payment is being processed through the system (status only applies to some cases, however the system must have notfications prepared for every transaction).
  • COMPLETE – payment completed successfully
  • REJECTED – payment rejection due to security reasons
  • CANCELED – payment cancellation
  • PARTIAL REFUNDED – partial refund (eg. one item)
  • REFUNDED – full refund of the payment

Integration credentials

To make the best out of the opportunities that G2APay offers you should get a unique API key and a secret token. Simply create an account on https://pay.g2a.com and go to Settings > Merchant.

Each REST API request have to contain authorization header. Authorization header is simple HTTP header Authorization with value {API_HASH};{HASH} – where:

  • API_HASH – this is your store API Hash from merchant panel
  • HASH – this value is string hashed using the SHA256 algorithm. String contains:
    • API Hash
    • Merchant email (G2A account name)
    • API Secret

Example

Variable Value
API_Hash 485d733d-7937-414a-8d42-6781397b1c0a
API_Secret pSO_-N%GZDGfpLu!a5qOUnA>T7QqOro?4?z~Lt5u@LKgg>X247PYvZX8gwy~YY=c
Merchant_Email merchant@my-test-store.com

Hash generation

Result:

9a67827ae58f013ab22a87c94135d6ce79366cecb79f725f483643b3e2f148ca

HTTP Header

Authorization: 485d733d-7937-414a-8d42-6781397b1c0a;
                            9a67827ae58f013ab22a87c94135d6ce79366cecb79f725f483643b3e2f148ca

Creating payment

The first step is to call Checkout URL for creating a new transaction.

G2APay Checkout will respond with the transaction identifier. The following step is to redirect to G2APay Checkout with new the transaction ID (received from API). Finally the user will be able to make a payment and be redirected to the merchant's website.

Starting a payment

To start a payment merchant application call G2APay Checkout using the POST method.

The request contains payment details, merchant API key and calculated hash string.

Calculating hash

Hash is a string generated by hashing certain payment details using the SHA256 algorithm:

{userOrderId}{amount}{currency}{ApiSecret}
  • userOrderId – merchant's order ID
  • amount – payment amount, rounded to 2 decimals
  • currency – currency,
  • ApiSecret – API Secret generated in merchant panel (Settings > Merchant)

More details about generating hashes is in the Notifications section.

POST request
POST https://checkout.pay.g2a.com/index/createQuote
POST body
api_hash=38be425a-63d0-4c46-8733-3e9ff662d62d
&hash=ac0945d82b8589959b5f4ffafcc1a6c5983e82b8b4094c377a7b9c43d4a432bc
&order_id=2845
&amount=15
&currency=EUR
&email=stefan@my-test-store.com
&url_failure=http://my-test-store.com/order/fail
&url_ok=http://my-test-store.com/order/success
&items=[{"sku":"450","name":"Test Item","amount":"15","type":"item_type","qty":"1","price":15,"id":"5619","url":"http://example.com/products/item/example-item-name-5619"}]
Variables
Field Data type Required Description
api_hash string Required Store API Hash
hash string Required Calculated hash
order_id string Required Merchant order ID
amount string Required Total order price
currency string Required Currency (ISO 4217)
description string NO Optional description
email string NO Return e-mail
url_failure string Required URL to redirect when payment fails
url_ok string Required URL to redirect the payment is successful
cart_type string NO Cart product type: physical or digital
items array Required Array of payment items
items[].sku string Required Item SKU
items[].name string Required Item name
items[].amount float Required Total item price (quantity x price)
items[].qty integer Required Item quantity
items[].extra string NO Item optional description
items[].type string NO Item optional type
items[].id string Required Unique item ID in your system
items[].price float Required Single item price
items[].url string Required Item URL
addresses array NO* Array of addresses
addresses[].billing array Required Array of billing address params
addresses[].shipping array Required Array of shipping address params
addresses[].billing[].firstname string Required First name
addresses[].billing[].lastname string Required Last name
addresses[].billing[].line_1 string Required Billing address line 1
addresses[].billing[].line_2 string Required Billing address line 2(could be an empty string)
addresses[].billing[].zip_code string Required Billing zip code (max length: 15 characters)
addresses[].billing[].city string Required Billing city
addresses[].billing[].company string Required Company name(could be an empty string)
addresses[].billing[].county string Required Billing county/region
addresses[].billing[].country string Required Country code(format ISO 3166-1 alpha-2)
addresses[].shipping[].firstname string Required First name
addresses[].shipping[].lastname string Required Last name
addresses[].shipping[].line_1 string Required Shipping address line 1
addresses[].shipping[].line_2 string Required Shipping address line 2(could be an empty string)
addresses[].shipping[].zip_code string Required Shipping zip code (max length: 15 characters)
addresses[].shipping[].city string Required Shipping city
addresses[].shipping[].company string Required Company name(could be an empty string)
addresses[].shipping[].county string Required Shipping county/region
addresses[].shipping[].country string Required Country code(format ISO 3166-1 alpha-2)

* If an integrated merchant who sells physical products by default should provide us with billing and shipping address details. If a merchant sells physical products, all the above is required. Addresses params are not required if the merchant does not sell physical products. However, if the merchant has already provided us with the billing/shipping address details, then all fields are required. The billing and shipping address can be the same.

Response
{
    "status": "ok",
    "token": "54f863189b6db"
}

Redirect

After the payment transaction has been started successfully the user should be redirected to G2APay Checkout Gateway with new token.

Example:

https://checkout.pay.g2a.com/index/gateway?token=54f863189b6db

After the user completes the payment they will be redirected to the merchant store – depending on the payment status they will be redirected either to url_ok or url_failure.

To url_ok will be passed GET parameter transactionId with newly created transaction ID.

Payment data

Current payment data can be retrieved using GET method.

Example GET request:

GET https://pay.g2a.com/rest/transactions/eac61839-7db6-4cab-8ec3-9708c4676938

Response

{
    "transactionId": "eac61839-7db6-4cab-8ec3-9708c4676938",
    "userOrderId": "70001010467320",
    "amount": 10.0,
    "currency": "EUR",
    "status": "complete",
    "createdAt": "2015-02-20 01:21:35",
    "refundedAmount": 0,
    "customer": {
        "firstName": "John",
        "lastName": "Doe",
        "address1": "",
        "address2": "",
        "postcode": "",
        "city": "Berlin",
        "country": "Germany"
    },
    "items": [
        {
            "sku": "item-124896",
            "name": "Test Payment Item",
            "amount": 8.0,
            "qty": 1
        },
        {
            "sku": "fee-091",
            "name": "Test Fee",
            "amount": 2.0,
            "qty": 1
        }
    ]
}

Response status

Below is a list of possible request responses.

HTTP Code Response Description
200 {transaction} Payment transaction found
403 forbidden Merchant is not allowed to use this method
404 not-found Cannot find transaction of given ID
500 error G2APay internal error

Notifications

G2APay send simple notifications after each change of a payment status – this is called IPN (Instant Payment Notification). To be able to receive these IPNs, first setup an appropriate URL where messages will be forwarded. To do this, enter https://pay.g2a.com and navigate to Settings > Merchant.

Notifications

Example

IPNs are sent in as RAW POST body. Below is a sample IPN with a confirmation that the transaction has been finished:

    type=payment
    &transactionId=eac61839-7db6-4cab-8ec3-9708c4676938
    &userOrderId=70001010467320
    &amount=100.0
    &currency=EUR
    &status=complete
    &orderCreatedAt=2015-02-20 01:21:35
    &orderCompleteAt=2015-02-20 01:25:51
    &refundedAmount=0
    &provisionAmount=0
    &hash=2a24c939992bc5b2e09480a7cb7acbf2cda32278ecca912457678008ff3a1fdf

IPN Hash

Each IPN has hash field which is calculated from transaction data. For security reasons this hash should always be checked in merchant application. The simplest way to confirm that the IPN is valid is to generate hash from data stored in the merchant database and compare with the one received in the IPN.

Hash is a string generated by hashing some transaction details using SHA256 algorithm:

{transactionId}{userOrderId}{amount}{ApiSecret}
  • transactionId – G2APay payment transaction ID
  • userOrderId – merchant's order ID
  • amount – payment amount, rounded to 2 decimals
  • ApiSecret – API Secret generated in merchant panel (Settings > Merchant)

Amount example

Original amount Rounded amount
2 2
2.2 2.2
2.21 2.21
2.234 2.23
2.235 2.24

Hash example

Field Value
transactionId ff4dce11-6064-4401-a621-86226aa5e599
userOrderId 985711
amount 20.51
ApiSecret 9pcrHX4irvG5=@$>qF-pUYnoR>@VJ?~SoR4!z8Zb+pgqgZpHoa!2$eqKdhpwfe9E</td>

String to hash:

ff4dce11-6064-4401-a621-86226aa5e59998571120.519pcrHX4irvG5=@$>qF-pUYnoR>@VJ?~SoR4!z8Zb+pgqgZpHoa!2$eqKdhpwfe9E

Hash:

1abadc9696537644b77274e953e145ec5b017b3257ff23d003c0b54c7ddbda98

Refunds

G2APay allow to refund payments. A refund request may be for full or partial. Partial refunds require that an amount is specified. The currency must match the initial order.

Several partial refund requests may be sent for a single payment transaction. A sum of requested values may not exceed the payment value.

Example

Authorization

Each request must contain Authorization header:

Authorization: {apiHash}; {authHash}
  • apiHash - It's API Hash of the store
  • authHash - Auth hash can be generated using SHA256 algoritm on string created from parameters:
{apiHash}{email}{apiSecret}
Processing refund

To process a refund for payment, call REST API:

PUT https://pay.g2a.com/rest/transactions/eac61839-7db6-4cab-8ec3-9708c4676938
With header:

Request contain transaction ID to refund, user order ID, amount, currency and hash. Hash is a string generated by hashing some details using SHA256 algorithm:

{transactionId}{userOrderId}{amount}{refundedAmount}{ApiSecret}

  • transactionId – G2APay payment transaction ID
  • userOrderId – merchant's order ID
  • amount – payment amount, rounded to 2 decimals
  • ApiSecret – API Secret generated in merchant panel (Settings > Merchant)

For more details see section Notifications.

Request payload:

action=refund
&amount=100.0
&hash=2a24c939992bc5b2e09480a7cb7acbf2cda32278ecca912457678008ff3a1fdf

Response JSON:

{
    "status": "ok",
    "transactionId": "eac61839-7db6-4cab-8ec3-9708c4676938"
}

This indicates that the request has been saved and will be processed. Change of payment status will be confirmed via IPN.

Response status

Below is a list of possible request responses.

HTTP Code Response Description
200 {result} Payment transaction set to refund
400 missing-parameters Some payment parameters are missing
400 invalid-hash Invalid hash string
400 invalid-amount Given amount is to high or less then minimum refund amount
400 invalid-action Invalid action provided
400 insufficient-funds Insufficient funds to process refund
401 unauthorized Authorization header is invalid
403 forbidden Merchant is not allowed to use this method
403 cannot-refund-transaction Transaction is in state that is not allowed to refund
404 not-found Transaction not found
500 error G2APay internal error

Subscriptions

G2A Pay allows receiving recurring payments as subscriptions for your service. Subscription will be set up on regular payment changing it to a periodical charge. You need to add few new parameters to your regular payment request in order to consider it as a subscription.

Activation

Before you will be able to receive payments for your subscription you need to activate it in Merchant Panel, please follow this link https://pay.g2a.com/merchant/subscriptions and complete required steps, please also keep in mind that you need to be a fully activated merchant to complete the process.

Setup

Gateway

If you use our gateway integration you need to add few new parameters to your POST body:

... other parameters ...
&subscription=1
&subscription_product_name=My+product+name+1+month
                            &subscription_type=product
&subscription_period=monthly
&subscription_start_date=2017-01-21
Variables
Attribute Value Data type Required Description
subscription 1 string Required Indicates about subscription setup
subscription_product_name {{PRODUCT_NAME}} string Required Name of your product/service
subscription_type {{TYPE}} string Required Type of subscription, allowed:
product|donation
subscription_period monthly string Required Subscription period, allowed:
monthly
subscription_start_date {{START_DATE}} string NO Optional, if subscription should start instantly leave it empty, format: YYYY-MM-DD

Notifications

G2A Pay send separated IPNs each time customer signup/deregister to your subscription.

Create

Below you will find sample IPN when user sign up to your subscription, we send to you POST data:

                            type=subscription_created
&subscriptionId=ece4c304-1964-4e33-bf46-0c6bd057ce23
&transactionId=39bba099-8193-4e8c-a3c2-ade7341f8628
&subscriptionName=Subscription+product+1+month
&subscriptionType=product
&period=monthly
&email=it12@g2a.com
&amount=10.00
&currency=USD
&status=active
&createdAt=2017-01-14T19:15:17+00:00
                            &nextChargeAt=2017-02-14T19:15:17+00:00
                            &disabledAt=
&hash=00ed7669a79c456dbeda6a0a248f594880bc3591fbcd6f46c12829f58710a6b8
            
Cancel

Each time subscription is being canceled you will receive IPN notification as POST data sent to your endpoint:

                            type=subscription_canceled
&subscriptionId=ece4c304-1964-4e33-bf46-0c6bd057ce23
&transactionId=39bba099-8193-4e8c-a3c2-ade7341f8628
&subscriptionName=Subscription+product+1+month
&subscriptionType=product
&period=monthly
&email=it12@g2a.com
&amount=10.00
&currency=USD
&status=canceled
&createdAt=2017-01-14T18:50:17+00:00
                            &nextChargeAt=
&disabledAt=2017-01-28T21:02:17+00:00
                            &hash=00ed7669a79c456dbeda6a0a248f594880bc3591fbcd6f46c12829f58710a6b8
            
IPN Hash

In order to validate IPN data as it should be done with regular IPN payment processing we always add hash parameter, for security reasons you should compare hash generated in your application with hash received in IPN data.

Hash parameter is generated by using SHA256 algorithm on concatenation of following data:

{subscriptionId}{amount}{subscriptionName}{apiSecret}
  • subscriptionId - subscription ID from IPN data
  • amount - amount from IPN data
  • subscriptionName - subscription name from IPN data
  • apiSecret - Your store API secret, which you will find in merchant panel (Merchant -> Settings)

Environments

  Production Sandbox
Quote URL https://checkout.pay.g2a.com/index/createQuote https://checkout.test.pay.g2a.com/index/createQuote
Merchant URL https://pay.g2a.com/ https://www.test.pay.g2a.com/
REST API https://pay.g2a.com/rest https://www.test.pay.g2a.com/rest
IPN IP   176.9.30.105

Supported CMS


osCommerce

osCommerce

osCommerce provides free e-commerce and online store platform solutions with a growing and active community of store owners and developers worldwide. Over 7,700 add-ons are available for free to use and professional development and support services are available through our certified partners to help increase your online sales.

G2A Pay has partnered with osCommerce to let you instantly access 150 payment methods with an easy integration.

Our module supports versions 2.3.4
Server requirements:
Supported PHP versions 5.4 or newer

Integrate now »
OpenCart

OpenCart

OpenCart is a free, open-source shopping cart solution full of features required to set up your own ecommerce store. The easy to use, responsive interface and a simple set up process allows you to create your new store in just a few quick steps. With its completely customisable design and over 13,000 available extensions, OpenCart is perfect for ecommerce stores of any size.

G2A Pay has partnered with OpenCart to let you instantly access over 150 payment methods with an easy integration.

Version supported 2.2 available in the back end
Server requirements:
Supported PHP versions 5.4 or newer

Integrate now »
PrestaShop

PrestaShop

PrestaShop provides more than 250,000 online store owners with the most powerful, dynamic and international ecommerce software enriched with hundreds of innovative tools to build and manage a successful online store at no cost.

G2A Pay has partnered with PrestaShop to let you instantly access over 150 payment methods with an easy integration.



Integrate now »

WooCommerce

Version supported 2.5 (based on WordPress 4.4)
Server requirements:
Supported PHP versions 5.4 or newer

Integrate now »

WHMCS

Version supported 6.2
Server requirements:
Supported PHP versions 5.4 or newer

Integrate now »

Shopware

Version supported 5
Server requirements:
Supported PHP versions 5.4 or newer

Integrate now »
Shopify

Shopify

Shopify is the leading cloud-based, multi-channel commerce platform designed for small and medium-sized businesses. Merchants use the software to design, set up and manage their stores across multiple sales channels, including web, mobile, social media, marketplaces, brick-and-mortar locations and pop-up shops. The Shopify platform was engineered for reliability and scale, making enterprise-level technology available to businesses of all sizes.

All versions supported


Integrate now »
HikaShop

HikaShop (Joomla)

HikaShop is an open source ecommerce solution for the Joomla CMS. It is made for simplicity and flexibility and comes in three editions, one of them being free to use.

Version supported 2.6.3
Server requirements:
PHP version v. 5.3.1 +
Joomla CMS engine v. 3.5.1 +


Integrate now »

VirtueMart (Joomla)

Version supported 3.0.16
Server requirements:
PHP version v. 5.3.1 +
Joomla CMS engine v. 3.5.1 +


Integrate now »

Drupal Commerce

Version supported 7.15
Server requirements:
PHP version v. 5.5 +
Drupal CMS engine v. 7.15 +


Integrate now »

Easy Digital Downloads (WordPress)

Version supported 2.6.4
Server requirements:
PHP version v. 5.5 +
WordPress version v. 4.0 +


Integrate now »

ZenCart

Version supported 1.5.5a
Server requirements:
PHP version v. 5.5 +


Integrate now »