Getting started

Foreword

The hosted-fields mode is the best compromise between security, ease of customisation and payment form integration.

This is a 2-step workflow:

  • Initiating an Hosted-fields payment form in order to generate tokens.
  • Using the token to send a payment request to the Payplug platform.

The first step uses Client’s level public API key while the second step uses Account’s level credentials :

Scope tree

This technical division allows you to use any Payplug Account during the second step, depending of the card / currency used by the cardholder.

Get your Payplug public API key

First of all, you must have received your public API Key email, which contains technical information:

  • API key ID
  • API key
  • URL to be used with your sandbox credentials
reminder

The URL and credentials to use for your transactions depend on the processing environment. During the integration and QA phase, we strongly recommend you to use the sandbox credentials.

You must also have received your Payplug Account’s credentials, which will be necessary to proceed the second step.

For further details, please refer to the API Key credentials section

Develop on the Sandbox environment

Any payment method must be developed on the sandbox test environment, before going live in production.

All transactions processed in the sandbox environment are simulated: no actual bank movements will occur.

security

Never send live traffic or real card details on this environment!

tips

You can use test card numbers (available on the payment method page) that will allow you to simulate different bank execution codes.

Paste the code into your website

Here is a fully functional example to initiate an hostel-field payment form. Just copy/paste HTML, CSS and JS code on your webpage and edit it to match your requirements:

  • form action URL must point to the post payment redirection page on your server;
  • Use your, API key ID and API key.
info

You can use this sandbox bank card number: 5555556778250000 .

tips

You can see this live example at: https://codepen.io/dalenys-paymentbe2bill/pen/b81e2210b98ea0ebf2dc77de3b92ddfc

See the Pen Basic Payplug-Payment hosted-fields by Dalenys (@dalenys-payment) on CodePen.

success

Submitting this form should allow you to retrieve the generated token.

Generate a request hash

Each request should be authenticated with a Payplug hash.

This requires the use of Payplug Account’s level credentials.

For further details, please refer to the authentication section.

Using the token to send a server to server payment request

$> curl --request POST --url "https://secure-test.dalenys.com/front/service/rest/process" \
--data "method=payment" \
--data "params[IDENTIFIER]=Demo Shop" \
--data "params[OPERATIONTYPE]=payment" \
--data "params[ORDERID]=1234" \
--data "params[AMOUNT]=1000" \
--data "params[CLIENTIDENT]=john.snow" \
--data "params[CLIENTEMAIL]=john.snow@example.com" \
--data "params[CLIENTREFERRER]=https://your_shop.com/order?id=1234" \
--data "params[CLIENTUSERAGENT]=Mozilla/5.0 (Windows NT 6.1; WOW64; rv:47.0) Gecko/20100101 Firefox/47.0" \
--data "params[CLIENTIP]=10.1.1.1" \
--data "params[CARDFULLNAME]=JOHN SNOW" \
--data "params[DESCRIPTION]=Knows nothing" \
--data "params[HFTOKEN]=17730892-b3f7-4411-bc81-557471ffcede" \
--data "params[HASH]=15477dcb8687adf90fa51e418f3c1a2d025f40b177a978c2734514734633b3c4" \
--data "params[VERSION]=3.0" \

Make sure to use your own IDENTIFIER and attach the hash that you calculated previously.

Handling the notification (IPN)

We strongly recommend you to integrate with a NOTIFICATION_URL.

Once the transaction status is known, a notification is sent to your URL.

The notification content must be used to update your application with the transaction result.

danger

In case the redirection has already been processed or in case you receive several notifications, be careful not to duplicate the transaction result.

security

You have to check the received HASH against the one you generate to confirm the request’s origin and integrity before redirecting the user. See this section for more information.

Please see the transaction notifications dedicated page.

What’s next?

Now you have integrated this simple payment workflow you can start thinking about: