Paybox integration using node.js – with example HTML

This post will help you get Paybox integration to work using node.js.

You can find a full working example in the `src/paybox-integration` dir of my blog code repository.

Paybox is a French payment provider. Getting their integration to work can be quite a hassle.

The simplest way to get payments to work, is to generate a form and post it to the paybox servers. This form must contain an HMAC signature based on your private HMAC key and the form data. It is rather tricky to get this right.

Unfortunately, if you do anything wrong with your form, you get a generic – and totally unhelpful – error message.

This does not help you debug your code.

Fortunately, there is a permanent test user on the paybox test environment. This can help you get it up and running. The test user has this HMAC key:

0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF0123456789ABCDEF

Here is a form that just works with the test user:

<form method="POST" action="https://preprod-tpeweb.paybox.com/cgi/MYchoix_pagepaiement.cgi">
<input type="hidden" name="PBX_SITE" value="1999888">
<input type="hidden" name="PBX_RANG" value="32">
<input type="hidden" name="PBX_IDENTIFIANT" value="107904482">
<input type="hidden" name="PBX_TOTAL" value="1000">
<input type="hidden" name= "PBX_DEVISE" value="978">
<input type="hidden" name="PBX_CMD" value="TEST Paybox">
<input type="hidden" name="PBX_PORTEUR" value="test@paybox.com">
<input type="hidden" name="PBX_RETOUR" value="Mt:M;Ref:R;Auto:A;Erreur:E">
<input type="hidden" name="PBX_HASH" value="SHA512">
<input type="hidden" name="PBX_TIME" value="2014-12-01T00:00:00+01:00">
<input type="hidden" name="PBX_HMAC" value="213904D9F3C6000C2892F1FD77795C58D0365B281136B3FA3B7EC530E4731A6D87D93D2268C0945C5EF5DF6496EECA329147F00113C4058402A4A2C060828DAA">
<input type="submit" value="Send">
</form>

Using the data in this form, you can figure out whether your HMAC algorithm is working correctly. We used the node-paybox module, which looks not that well maintained, but it works well.

This is how we use it:

var transactionData = {
  offer   : 'system', // always 'system'
  isTest  : isTest,   // true to use the paybox test system
  key     : process.env.PAYBOX_HMAC_KEY,
  PBX_    : {
    SITE       : process.env.PBX_SITE,
    RANG       : process.env.PBX_RANG,
    IDENTIFIANT: process.env.PBX_IDENTIFIANT,
    TOTAL      : amountPayableInCents,
    DEVISE     : '978', // currency in ISO 4217 - 978 is EUR

    // Do not include colons (":") in the payment id (PBX_CMD).
    // If you do, the node-paybox module will not succeed in verifying
    // the signature of the message. It seems to have something to do
    // with the : not properly being URL encoded.
    CMD        : 'some unique identifier without :',
    PORTEUR    : emailAddress,

    // Make sure that 'sign:K' is the last parameter, otherwise the signature
    // validation might fail!
    RETOUR     : 'value:M;id:R;auth:A;error:E;transactionTime:Q;transactionDate:W;transactionNumber:S;sign:K',
    HASH       : 'SHA512',
    TIME       : transactionTime.toISOString(),
    REPONDRE_A : baseUrl + '/callback',
    ANNULE     : baseUrl + '/cancel',
    ATTENTE    : baseUrl + '/pending',
    EFFECTUE   : baseUrl + '/ok',
    REFUSE     : baseUrl + '/error',
  }
};

paybox.createTransaction(transactionData, function(err, transaction) {
  // Display a form using transaction.method, transaction.url and transaction.body
});

Hopefully this will help you in getting Paybox integration to work. For a working example, see the `src/paybox-integration` dir of my blog code repository.