ClubCollect
Search…
Payments
Use ClubCollect as your payment provider
get
https://app.clubcollect.com/api/v2/payments
/:payment_method
Start Payment

Signature

To ensure authenticity and data integrity of incoming payment requests ClubCollect requires these requests to be signed. This signature is based on a Hash-based Message Authentication Code (HMAC) calculated using a request's key-value pairs and a secret key, which is known only to the partner and ClubCollect.
Before sending a payment request to ClubCollect, the partner has to calculate the signature and add it as a request parameter. When a request comes in, ClubCollect calculates the same signature based on the received key-value pairs and the secret key. By verifying that both signatures are equal, ClubCollect ensures that the request is not tampered.
Similarly, the partner can validate responses from ClubCollect by calculating the corresponding signature and comparing it with the signature in the response.
Let's explain now how to calculate the signature step by step using the key-value pairs in the table below as example.
Note that code snippets are provided in Ruby.
key
value
first_name
John
redirect_url
http://partner-test.nl
country_code
NL
external_invoice_number
123456
amount_cents
1000
last_name
Doe
locale
company_id
d4b8772c67154a6bced8a8b827e177cc00111fe0
payment_reference
Club membership 2019/2
partner API key: 3ac2bf2359c1eb184fe0fea01f624bc1d8581981
    1.
    Discard key-value pairs for which value is null or an empty string
key
value
first_name
John
redirect_url
http://partner-test.nl
country_code
NL
external_invoice_number
123456
amount_cents
1000
last_name
Doe
company_id
d4b8772c67154a6bced8a8b827e177cc00111fe0
payment_reference
Club membership 2019/
    1.
    Sort the key-value pairs by key.
key
value
amount_cents
1000
company_id
d4b8772c67154a6bced8a8b827e177cc00111fe0
country_code
NL
external_invoice_number
123456
first_name
John
last_name
Doe
payment_reference
Club membership 2019/2
redirect_url
http://partner-test.nl
    1.
    Concatenate every key-value pair on the list obtained in the previous step to get the signing string
1
signing_string = params.keys.sort.flat_map { |k| [k, params[k]] }.join
Copied!
1
amount_cents1000company_idd4b8772c67154a6bced8a8b827e177cc00111fe0country_codeNLexternal_invoice_number123456first_nameJohnlast_nameDoepayment_referenceClub membership 2019/2redirect_urlhttp://partner-test.nl
Copied!
    1.
    Calculate SHA256 digest of the signing string
1
digested_content = Digest::SHA256.digest(signing_string)
Copied!
1
\tD!()\xAFL\xED\x069\xC0\xEC\x11/\xB3\x93\xFAM\xC0\xA9\xE7\x03\x03\e\xDC\xDFF\x9FZ\x15\xD6\xD1
Copied!
    1.
    Calculate HMAC SHA-256 signature of digested signing string using the API key.
1
hmac_binary = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), api_key, digested_content)
Copied!
    1.
    Encode the result from binary to hexadecimal
1
signature = hmac_binary.unpack1('H*')
Copied!
    1.
    The signature calculated for the example key-value pairs and API key is:
1
754966cc8946c8125b365fcb5cf0e27edd98fe7516de7ea17f1b5254bcf7a00e
Copied!
    1.
    After the signature is generated, it has to be appended to the url query string as
1
&signature=754966cc8946c8125b365fcb5cf0e27edd98fe7516de7ea17f1b5254bcf7a00e`
Copied!

Payment response

Once the users finish the payment process, they are redirected to a result page of your choice, included in the payment request as redirect_url.
ClubCollect will append parameters to this URL. payment_result will inform the partner about the payment status. If the status is already determined (either authorised or refused or cancelled), this information can be used to display a payment successful or payment failed or payment cancelled page.
In a case when the current status is pending, the outcome of the payment will be communicated with payment notifications. Payments with status cancelled may be authorized later by the payment provider.
The partner is encouraged to store the invoice_id and payment_id returned in ClubCollect responses and payment notifications, they will be needed to track the status of the payments. As an alternative, the partner can provide a unique external_invoice_number parameter in the payment request and ClubCollect will include it on the response and notifications.
The payment_result can have one of these values:
    authorized - the payment was successfully processed and accepted by the payment provider
    refused - the payment could not be processed due to invalid data introduced by the user
    cancelled - the payee cancelled the payment or the payment session was ended by the payment provider due to inactivity of the payee.
    pending - the payment is submitted for processing but the payment provider hasn't sent yet the result
    error - the request was invalid or there was a general error on provider side (payment state is unknown)

Payment notifications

For some online payment methods such as iDEAL, the outcome of the payment request might take several hours to confirm. As soon as ClubCollect receives any update from the payment provider, a payment notification will be sent to the partner to communicate any change in the payment status.
Notifications are sent as HTTPS callbacks (webhooks) to an endpoint on your server. To receive notifications, you need a server that has:
    An endpoint that can accept a JSON payload in an HTTP POST request.
    An open TCP port for HTTPS traffic
This endpoint should be communicated to ClubCollect before going live with the payment integration.
The format of the JSON payload sent in the notifications is as follows:
1
{
2
"api_key": "<secret-partner-api-key>",
3
"company_id": "<unique-company-id>",
4
"invoice_id": "<unique-invoice-id>",
5
"external_invoice_number": "<unique-partner-invoice-number>",
6
"payment_id": "<unique-payment-id>",
7
"payment_method": "ideal",
8
"payment_result": "authorized|cancelled"
9
}
Copied!
get
https://app.clubcollect.com/api/v2/payments
/:id
Check status of a payment
get
https://app.clubcollect.com/api/v2/payments
/notifications
Payment notifications feed
Last modified 6mo ago