Payment Authentication

Credentials

Payplug technical accounts require credentials to be used.

There are 2 main kinds of credentials depending of the integration mode and your integration concerns.

Standard credentials

These identifiers are dedicated to most online store configurations.

  • ACCOUNT_KEY string (16)

    Account’s key associated with an IDENTIFIER.

    Example: Y#iK*h-fZ>E<:7Ai

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

security

The Payplug ACCOUNT_KEY is confidential and should be kept safely.

API KEY credentials

These identifiers are dedicated to specific online store configurations, as mobile application or SDK, and make it possible to carry out a restricted list of operations.

  • APIKEY string (16)

    The API key, private or public value (depending on the API KEY type) associated with an APIKEYID.

    Example: a1b2c3d4e5f6g7h8

  • APIKEYID string (36)

    An ID associated to the APIKEY. This parameter must be included in each transaction request.

    Example: a688b3a1-d227-4cdd-9454-5d7cfcc74ef9

  • IDENTIFIER string(1-32)

    Your processing account technical identifier.

    Example: Demo Shop

info

An APIKEY is shared by all your technical accounts. To use a specific account, just use the corresponding IDENTIFIER with your APIKEY.

There are also 2 kinds of APIKEY credentials:

  • SDK: Dedicated for any SDK framework, please ask your account manager for further information;
  • Notification / redirection: Used to recalculate a notification and redirection HASH (Please refer to the dedicated chapter)

For each of them, the set IDENTIFIER + APIKEY, as well as all the parameters of the request are necessary to the calculation of the hash, as explained below.

HASH Generation

Every Payplug request must be signed with a HASH parameter. This HASH parameter ensure the request’s origin (authentication) and integrity (no alteration by a third).

The HASH parameter must be composed of the following concatenation :

  • Your ACCOUNT_KEY or when appropriate, the APIKEY ;
  • All request parameters and sub-parameters sorted alphabetically (A-Z) formatted FIELD=VALUE and separated by your key (ACCOUNT_KEY or APIKEY);
  • The resulting string must be hashed with a sha256 function.
security

The Payplug ACCOUNT_KEY is confidential and should be kept safely.

Examples

Standard credentials

Considering a request with these parameters:

{
    "ORDERID": "000123",
    "DESCRIPTION": "sample HASH",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CLIENTIDENT": "client_123",
    "VERSION": "3.0",
    "OPERATIONTYPE": "payment"
}

And your key is “SECRET”, you will have to generate this clear text string

SECRETAMOUNT=1000SECRETCLIENTIDENT=client_123SECRETDESCRIPTION=sample HASHSECRETIDENTIFIER=SAMPLE_SHOPSECRETOPERATIONTYPE=paymentSECRETORDERID=000123SECRETVERSION=3.0SECRET

The sha256 to generate will be:

bc27d2033fc407300d0172b6886be8b00009e910d2a80fbbe420f2a90c0055e7

API KEY credentials

Considering a request with these parameters:

{
    "ORDERID": "000123",
    "DESCRIPTION": "sample HASH",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CLIENTIDENT": "client_123",
    "VERSION": "3.0",
    "OPERATIONTYPE": "payment",
    "APIKEYID": "a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6"
}

And your key is “SECRET”, you will have to generate this clear text string

SECRETAMOUNT=1000SECRETAPIKEYID=a1b2c3d4-e5f6-g7h8-i9j0-k1l2m3n4o5p6SECRETCLIENTIDENT=client_123SECRETDESCRIPTION=sample HASHSECRETIDENTIFIER=SAMPLE_SHOPSECRETOPERATIONTYPE=paymentSECRETORDERID=000123SECRETVERSION=3.0SECRET

The sha256 to generate will be:

c9c21c6341431e4fa387805cac2fe04a3623802da52ac0361783dd9943cbfa87

General purpose

tips

The HASH parameter itself should not be include in the calculation.

info
  • The parameters that are not listed in the Payplug documentation should not be included in the HASH calculation (e.g. submit button, hidden input, csrf token, etc.).
  • In case of server to server requests you won’t integrate method in the HASH clear string.
warning

This HASH generation algorithm is intended to be really sensible to string variations. Pay attention when generating the clear string to respect the word case, the text encoding and any other possible source of variance which could impact the HASH generation.

Excluding method from the hash calculation

Considering a request with a payment method and these parameters:

{
   "method": "authorization",
   {
    "ORDERID": "000123",
    "DESCRIPTION": "sample hash",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CLIENTIDENT": "client_123",
    "VERSION": "3.0",
    "OPERATIONTYPE": "payment",
   }
}

And your key is “SECRET”, you will have to generate this clear text string (method is always excluded from the hash calculation)

SECRETAMOUNT=1000SECRETCLIENTIDENT=client_123SECRETDESCRIPTION=sample hashSECRETIDENTIFIER=SAMPLE_SHOPSECRETOPERATIONTYPE=paymentSECRETORDERID=000123SECRETVERSION=3.0SECRET

The sha256 to generate will be:

ae96fd4faf3d66cb84f4eaa98034efc6b37864f1b1674ec19a4d1f8660fb27f4

Use cases

The HASH mechanism is used to protect the requests processed between Payplug and your website against alteration (integrity) and unauthorized service use (authentication).

This mechanism is used for various operations of the Payplug API.

You have to supply a well formatted HASH parameter in following cases (not exhaustive listing):

  • While submitting a request (server to server calls)
  • While redirecting a user with some parameters (e.g. hosted form)

The requests from the Payplug platform to yours are protected with the same HASH mechanism. You definitively want to check the request integrity by comparing the supplied HASH with another one you have to generate from the request parameters.

You have to check the received HASH parameters in the following cases (not exhaustive listing):

  • Payment notification requests (IPN) on NOTIFICATION_URL from the Payplug platform
  • Template url call on TEMPLATE_URL from the Payplug platform
  • User redirect to your website through REDIRECT_URL from the Payplug platform
danger

If you do not properly check the received HASH from a request sent by the Payplug platform, you may suffer from severe security issues since anybody could create or alter the request and change some parameters.

Nested parameters

In specific cases, some nested parameters are used in a request.

Example
{
    "ORDERID": "000123",
    "AMOUNT": "1000",
    "IDENTIFIER": "SAMPLE_SHOP",
    "CART": [
        {
            "NAME": "product 1",
            "AMOUNT": 500
        },
        {
            "NAME": "product 2",
            "AMOUNT": 500
        }
    ],
    "VERSION": "3.0"
}

To calculate the HASH for a request containing nested parameters, you have to serialize them in the following order (API_SECRET_KEY = ‘SECRET’):

SECRETAMOUNT=1000SECRETCART[0][AMOUNT]=500SECRETCART[0][NAME]=product 1SECRETCART[1][AMOUNT]=500SECRETCART[1][NAME]=product 2SECRETIDENTIFIER=SAMPLE_SHOPSECRETORDERID=000123SECRETVERSION=3.0SECRET

The final resulting HASH after the sha256 processing would be:

18c9007f844333a91202470c38e49227966e0b7597d672357a8985062a33c6bf