September 22, 2017, 6:28 pm

Print

What is PG-1 API and how to use it?


Date added:
28 February 2012
Last revised:
23 October 2012

Answer

PG-1 APIs (Application Programming Interfaces) is a web service provided by PG-1 to automate your business. With this service, your website can execute certain actions related with any payment received to your merchant account which includes:

  • Payment Approval/Rejection
    For every payment received to your merchant account, we will send an Instant Payment Notification (IPN) to your website. You can either approve (the payment will be received to your PG-1 merchant account), or reject the payment (the payment will be refunded to the buyers PG-1 account).
  • Payment Refund
    For every payment that has not been approved/rejected yet, you can issue partial refunds. Example: payment amount 100.000, you can issue a refund of 30.000 back to the buyer, and when you have approved the payment the remaining payment amount will be received to your PG-1 merchant account. This feature will be useful to automate a partial order cancel / order price changes.
  • Payment Split
    For every approved payment, you can issue payment splits to another PG-1 account. This feature will be useful to automate the payment to any third party for every payment received (example: pay commission, pay for the product cost / shipping cost to the vendor, etc.)
  • Batch Process
    In some cases you will need multiple actions to be executed at once (one API call), which means if one of the action is failed, all the actions will be invalid / rollback. For example, you want to execute these actions at once: Approve Payment A, Approve Payment B, Reject Payment C, Split Payment A, and Refund Payment D. If any of those action is failed, for example the split payment is failed because the split amount is exceeds the remaining payment amount, then all of the actions will be ignored/rollback automatically (no changes will be made).

 

Enable API Access

Please follow these steps to enable/activate your API Access:

  • Login to your merchant account, and select Manage Store
  • Click on API Access button for your registered website
  • To enable the API Access you must read and agree with the PG-1 API Access terms and conditions. Check the "I have read and agreed with the PG-1 API Access terms and conditions" and input your PIN, then click Request API Key button.
  • If succeed, you will get API Access Key and API Secret Key. To secure the access to your API, you should keep your API Secret Key privately and you can restrict the access to certain IP Address if needed.

 

Understanding the API Call

After successfully enabling your API Access, you can start accessing it from your website. The API call basically is just a regular HTTP POST/GET request secured by HTTP Basic Authentication. For the HTTP Basic Authentication you will need to submit username & password as follow:

  • Username
    For the username, use your API Access Key. The API Access Key is generated when enabling the API Access for your registered website (see steps to enable API Access above).
  • Password
    For the password, you will need to submit the Request Signature. Request Signature is a hash key you will generate with certain algorithm which include the request parameter and your API Secret Key. This signature will uniquely secure you request from any unauthorized tampering attempt, as the only one who can generate the valid hash key is your website. You can see the algorithm used to generate your Request Signature at the following section of this article.

For every API call you will need to submit these POST/GET parameters:

  • trx-id
    Trx ID is the PG-1 hash code that you receive in the Instant Payment Notification. It will be a unique reference to the payment transaction you want to process.
  • ts
    Ts is the API request time stamp (when the HTTP request submitted) in the Coordinated Universal Time (Greenwich Mean Time) time zone. The time stamp will use ISO 8601 format (Example: 2007-01-31T23:59:59Z).

The API Call Response will be in JSON format, which includes "success" attribute (the value can either be true or false) indicating if the call is successfully executed or not. Response Example:

{"description":"The Payment Transaction has been approved successfully","success":true,"version":"1.0"}

 

How to generate Request Signature

Please follow these steps to generate the API Request Signature:

  • Sort The Parameters Ascending (a-z)
    • Example: The parameters you want to submit for the Approve Payment API are:
      • store-id=10000
      • merchant= This e-mail address is being protected from spambots. You need JavaScript enabled to view it
      • ts=2012-01-09T01:02:16Z
      • trx-id=K9SKD242-028SNBAS-CS0A82J1-8852HS02
    • Sort it by the parameter name so it should be at this order:
      • merchant= This e-mail address is being protected from spambots. You need JavaScript enabled to view it
      • store-id=10000
      • trx-id=K9SKD242-028SNBAS-CS0A82J1-8852HS02
      • ts=2012-01-09T01:02:16Z
  • Generate the Request Parameter URL
    Join all the parameters with the ampersand character (&), and encode the parameter name and value according to RFC 3986 (URL Encode). After the joined & encoded, the request parameter URL will be something like this:
    merchant=merchant%40payglobalone.com&store-id=10000&trx-id=K9SKD242-028SNBAS-CS0A82J1-8852HS02&ts=2012-01-09T01%3A02%3A16Z
  • Generate HMAC hash and Encode with Base64 Encoding
    • Generate raw HMAC hash with sha256 algorithm for the Request Parameter URL generated above using your API Secret Key.
    • Then encode the raw HMAC hash with Base64 Encoding algorithm. For example, if your API Secret Key is: Uuck6nLD3jHrLxgVMaiziEiSSXkgcLw2P4uHdZbN, after encoding the raw HMAC hash with Base64 algorithm, you will get the valid signature for the example request above as follow:
      TULqbDvSE0SW3GRxJEClaJVtBdEn1TY96tsmBaBZ37U=
    • The generated Request Signature will be used for the password in HTTP Basic Authentication during the API Request Call (use your API Access Key as the username).

 

How to make the API Call

We have created a library in some programming language. You can use the library to make the API call (documentation & samples are included) to PG-1 web service. The library can be downloaded at the download section of PG-1 Developer page.

 

The list of available APIs

Below are the list of APIs you can access:

  • Approve Payment
    URL Access: https://secure.payglobalone.com/api/v1/approve-payment.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • trx-id (String)
      The PG-1's hash code for the transaction you want to approve
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"description":"The Payment Transaction has been approved successfully","success":true,"version":"1.0"}

  • Reject Payment
    URL Access: https://secure.payglobalone.com/api/v1/reject-payment.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • trx-id (String)
      The PG-1's hash code for the transaction you want to reject
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"description":"The Payment Transaction has been rejected successfully","success":true,"version":"1.0"}

  • Refund Payment
    URL Access: https://secure.payglobalone.com/api/v1/refund-payment.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • trx-id (String)
      The PG-1's hash code for the transaction you want to refund. The payment should NOT be rejected/approved to be eligible for the refund
    • description (String)
      Fill with the reason for the refund. This reason will showed at buyer history
    • amount (Numberic)
      Fill with the refund amount. The amount cannot exceeds the remaining payment amount
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"description":"Payment Refund has been processed successfully","success":true,"version":"1.0"}

  • Split Payment
    URL Access: https://secure.payglobalone.com/api/v1/split-payment.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • trx-id (String)
      The PG-1's hash code for the transaction you want to split. The payment have to be approved first before it can be split
    • target (String) - can occurred more than once
      The value this parameter is a JSON String, which has with these attributes:
      • target (String)
        Fill with the receiver/target PG-1 email address.
      • description (String)
        Fill with the split description. This description will be showed at the receiver history.
      • type (String)
        The valid amount type are: gollar, reward.
      • amount (Numeric)
        Fill with the split amount. The amount cannot exceeds the remaining payment amount.
      Example: {"target":" This e-mail address is being protected from spambots. You need JavaScript enabled to view it ", "description":"Commission 1", "type":"gollar", "amount": 2000}
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"description":"Payment Split has been processed successfully","success":true,"version":"1.0"}

  • Batch Process
    URL Access: https://secure.payglobalone.com/api/v1/batch-process.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • action (String) - can occurred more than once
      The value this parameter is a JSON String, which has with these attributes:
      • action (String)
        The valid action type value: approve, reject, refund, split.
      • Action Parameters
        The parameters for each related action in JSON string format.
      Example: {"action":"approve", "trx-id":"K9SKD242-028SNBAS-CS0A82J1-8852HS02"}
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"description":"Batch Actions has been processed successfully","success":true,"version":"1.0"}

  • Check Payment Status
    URL Access: https://secure.payglobalone.com/api/v1/check-payment.act
    Basic Authentication: API Access Key & Request Signature
    Parameters:
    • merchant (String)
      Your merchant account primary email address
    • store-id (Numberic)
      Your registered Store ID related with the access-key
    • trx-id (String)
      The PG-1's hash code for the transaction you want to check
    • ts (String)
      The request UTC time stamp

    Success Response:
    {"trx-status":"approved/rejected/confirmed", "original-amount":71000, "fee":2000, "received-amount":69000, "success":true,"version":"1.0"}

Category

Tags for this item