Integration of the Pledg payment solution

# Back mode

# Use case

See here.

# Sequence diagram

# Integration

# PSP supported

The PSP currently supported are the following :

  • Adyen
  • Alipago (Colombia, Mexico)
  • Be2bill
  • Bluesnap
  • Braintree
  • CentralPay
  • Checkout.com
  • Credorax
  • Cybersource
  • dLocal
  • Dalenys
  • Evolve
  • Fondy
  • Halyk bank
  • Hipay
  • iPay
  • Mercanet
  • MercasoPago (Chile, Argentina)
  • Midtrans
  • Monetico
  • Pay ON
  • PayBox
  • PayU
  • Payline
  • Payvision
  • Payzen
  • ProPay
  • Safecharge
  • Sogecommerce
  • Sogenactif
  • Stripe
  • SystemPay
  • Truevo
  • Worldline (Ogone, Ingenico, Sips, ...)
  • Worldpay
  • Yigim

If the PSP of the Merchant is not in this list, Pledg can most of times add it via a specific development.

# Adyen

When the PSP of the merchant is Adyen, the merchant must provide to Pledg the following parameters:

description
Account username
Password
Your merchant account (upper left hand corner of your Adyen dashboard)

# SystemPay / PayZen

When the PSP of the merchant is SystemPay or Payzen, the merchant must provide to Pledg the following parameters:

  • For SOAP webservices:
description
Shop id
Production Certificate
  • For REST webservices:
description
username
password

# Ogone

Note: Ogone is now part of Ingenico

When the PSP of the merchant is Ogone, the merchant must provide to Pledg the following parameters, required to setup the processout connector:

description details
Login Merchant account on Ogone's platform.
User Api user
Password Password of the Api user
Signature
Signature encryption Signature algorithm: can be sha1, sha256 or sha512

Important:

  • Pay attention to Lowercase/Uppercase
  • To create Api user/Api password: here (opens new window)
  • Signature: Must NOT contain the [ (bracket) character
  • The processout connector mentions some @IPs to be whitelisted. They have to be added by the merchant in their Ogone Directlink configuration as per doc #2.3.3 IP address (opens new window).
  • Merchant MUST ask to Ogone/Ingenico to enable the Server-to-Server API

Already faced errors, while testing the processout connector:

# Result

The general principles of the result passed to the merchant frontend are detailed there.

# Standard result

The structure of the result is:

{}

# Former Standard result (now deprecated)

The structure of the result (which is independent of the merchant PSP) is:

{"transaction": {"created_at": "2018-12-10T16:12:36.122775Z",
                 "error": null,
                 "id": "psp_id",
                 "sandbox": False,
                 "status": "completed"},
 "purchase": {"meta_data": {"departure-date": "2022-03-30"},
              "reference": "PLEDG_6500735432411",
              "uid": "pur_c9299823-810e-4e8b-a7c3-bde856e6840c"}
}

The id is the true PSP id (for example Stripe), not the Pledg id. It can be retrieved in the PSP dashboard.

The transaction statuses are documented there (opens new window).

# Payzen result

The structure of the result passed to onSuccess is:

{"transaction": {"created_at": "2018-12-10T16:12:36.122775Z",
                 "error": null,
                 "id": "payzen_transaction_id",    # ex 9xxxx7
                 "uid": "payzen_transaction_uid",  # ex a717ae49e2844cb19ef19a702dc1xxxx
                 "status": "payzen_status_label",  # always AUTHORISED
                 "reference": "foo-bar-baz"},
 "purchase": {"meta_data": {"departure-date": "2022-03-30"},
              "reference": "PLEDG_6500735432411",
              "uid": "pur_c9299823-810e-4e8b-a7c3-bde856e6840c"}
}

The Payzen web service createPayment called by the back returns in paymentResponse the transaction id and uid:

  • the uid is the new Payzen id, which is the one to be used
  • the id is the old Payzen id, still provided for backward compatibility

For more information, see Payzen documentation. Chapter 5 (opens new window).

paymentResponse also contains the values responseCode and transactionStatusLabel.

If responseCode is different from 0, an error is passed to the merchant frontend.

If transactionStatusLabel is different from AUTHORISED, an error is passed to the merchant frontend.

In the result above, status contains the transactionStatusLabel value, i.e. AUTHORISED.

For more information, see Payzen documentation, commonResponse page 47 (opens new window).

The result can be provided as a JWT, encoded with a secret shared between Pledg and the merchant.

# Notification

The general principles of the notification sent to the merchant backend are detailed there.

# Standard notification

# Body

The JSON contains the details of the transaction completed by the PSP.

The structure of the JSON is the following:

POST /merchant_payment_notification_url

{"created_at": "2019-04-04T12:20:34.97138Z",
 "id": "test-valid",
 "additional_data": {"xx": "yy"},
 "metadata": {"foo":"bar"},
 "status": "completed",
 "sandbox": "true",
 "error": "",
 "reference": "PLEDG_1086986786391",
 "signature": "B1C777835C01CA96AC4C3097FD46A7CA49B92BE157EDE0CB3552880D12A15359"}

additional_data contains optional additional data sent by the PSP, for example ids to make refunds.

metadata contains optional metadata sent originally by the merchant. This can be useful to allow the merchant to map the incoming notifications with the original purchases.

The transaction statuses are documented there (opens new window).

# Signature

This webhook has a signature field to check that it was sent from Pledg.

Pledg will create a secret key for the merchant, and the merchant will use it to check the signature following those steps:

Here are the notification keys used to calculate the signature(=hash):

  • created_at
  • error
  • id
  • reference
  • sandbox
  • status

Please note that you must not use the additional_data, metadata and signature keys.

Here is an example with the secret key as SECRET.

  1. Sort by alphabetic order these parameters:
{"created_at": "2019-04-04T12:20:34.97138Z",
 "error": "",
 "id": "test-valid",
 "reference": "PLEDG_1086986786391",
 "sandbox": "true",
 "status": "completed"}
  1. Concatenate the parameters in the form key=value with the secret key between two parameters:
created_at=2019-04-04T12:20:34.97138ZSECRETerror=SECRETid=test-validSECRETreference=PLEDG_1086986786391SECRETsandbox=trueSECRETstatus=completed
  1. Apply the SHA256 algorithm to the string: (you can check it with https://passwordsgenerator.net/sha256-hash-generator/)
B1C777835C01CA96AC4C3097FD46A7CA49B92BE157EDE0CB3552880D12A15359
  1. Check the value of the signature field received.

# Payzen notification

The merchant must specify at the purchase creation the webhook URL to be called at the end of the payment.

This webhook URL is an optional parameter of the purchase: paymentNotificationUrl.

If the merchant uses the SOAP webservice of Payzen via Pledg, Payzen does not send any IPN, because the payment is completed server-to-server. The Pledg platform then sends the same notification as the one Payzen should have sent, so that the integration is seamless for the merchant.

If the merchant uses the REST webservice of Payzen via Pledg (=server to server api "WS_REST_CARD_ENTRY"), Payzen does not send any IPN. Pledg sends its standard notification (refer to standard format) with uid as an additionnal key. This key must be included when calculating the signature/hash of the notification.

# Ogone notification

The principle is exactly the same as for SOAP webservice of Payzen, for the same reasons.

← Transfer mode →