Payments

Use ClubCollect as your payment provider

get
iDEAL payments

https://app.clubcollect.com/api/v2/payments/ideal
This endpoint allows to start a new iDEAL payment and redirects the user to the payment page.To start the payment session, the partner needs to generate the payment URL with the required parameters and add a signature to avoid tampering with data. Payments will always be linked to an invoice in ClubCollect. The invoice will be created ad hoc from the parameters received in the request, unless the partner provides the invoice_id of an existing invoice to be paid. When the invoice_id is given, the payment will be generated for the total amount due for the invoice.The invoices that are generated ad hoc are grouped in batches, per month. These batches can be found on :https://app.clubcollect.com/treasurer/import_batches, named iDEAL (<year>-<month>) by default, e.g. iDEAL (2019-08).
Request
Response
Query Parameters
company_id
required
string
Unique identifier of the company receiver of the payment.
redirect_url
required
string
When payee completes or canceles the payment process, the request will be redirected to this URL. ClubCollect will append some additional parameters to the request which will allow the partner to know the current state of the payment. See below in the response section.
signature
required
string
Request signature
invoice_id
optional
string
ID of an invoice that has been already generated by the partner for the payee. In case it's provided, the payment generated will be for the total amount due for the given invoice. This can be used by the partner when the payee starts the payment process and the payment is left incomplete or it's cancelled.In case invoice_id is given, amount_cents, last_name and the rest of parameters below will be ignored. These are used only to generate a new invoice.
last_name
required
string
Last name of the payee. Required unless invoice_id is provided.
amount_cents
required
integer
Amount in cents that is going to be paid. Required unless invoice_id is provided.
payment_reference
optional
string
Reference of the payment, will be used as description of the invoice line.
first_name
optional
string
First name of the payee.
external_invoice_number
optional
string
Unique invoice number provided by the partner.
locale
optional
string
Language that will be used in the payment process. If not given, the company default locale will be used.
first_name
optional
string
First name of the payee.
prefix
optional
string
Prefix of the name of the payee.
infix
optional
string
Prefix of the name of the payee.
country_code
optional
string
Payee country, as defined by ISO 3166-1 alpha-2 standard.
address1
optional
string
Payee street name
house_number
optional
string
Payee address number
zipcode
optional
string
Payee ZIP code. If it's given, it must be less than 16 characters.
city
optional
string
Payee city. If it's given, it must be less than 35 characters.
email_address
optional
string
Payee email address.
phone_number
optional
string
Payee phone number.
302: Found
The payment request is valid, the payee is redirected to the payment page and completes the payment process. The user will be redirected to the redirect_url specified by the partner in the payment request and the parameters listed below will be appended to the URL. The signature added by ClubCollect will be generated only for these parameters added by ClubCollect.
company_id=<unique-company-id>&
invoice_id=<unique-invoice-id>&
external_invoice_number=<unique-partner-invoice-number>&
payment_id=<unique-payment-id>&
payment_method=ideal&
payment_result=<authorized|cancelled|pending|refused|error>
422: Unprocessable Entity
The payment request has any invalid parameters, or any required parameter is not given. ClubCollect will redirect to the `redirect_url` provided by the partner appending `error_code` and `error_details` to the response.
company_id=25b39de9bedc3409e195a99bb3a31918c12182e7&
payment_method=ideal&
error_code=unprocessable_entity&
error_details=invalid_signature;invalid_partner

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/

2. 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

3. Concatenate every key-value pair on the list obtained in the previous step to get the signing string

signing_string = params.keys.sort.flat_map { |k| [k, params[k]] }.join
amount_cents1000company_idd4b8772c67154a6bced8a8b827e177cc00111fe0country_codeNLexternal_invoice_number123456first_nameJohnlast_nameDoepayment_referenceClub membership 2019/2redirect_urlhttp://partner-test.nl

4. Calculate SHA256 digest of the signing string

digested_content = Digest::SHA256.digest(signing_string)
\tD!()\xAFL\xED\x069\xC0\xEC\x11/\xB3\x93\xFAM\xC0\xA9\xE7\x03\x03\e\xDC\xDFF\x9FZ\x15\xD6\xD1

5. Calculate HMAC SHA-256 signature of digested signing string using the API key.

hmac_binary = OpenSSL::HMAC.digest(OpenSSL::Digest.new('sha256'), api_key, digested_content)

6. Encode the result from binary to hexadecimal

signature = hmac_binary.unpack1('H*')

7. The signature calculated for the example key-value pairs and API key is:

754966cc8946c8125b365fcb5cf0e27edd98fe7516de7ea17f1b5254bcf7a00e

8. After the signature is generated, it has to be appended to the url query string as

&signature=754966cc8946c8125b365fcb5cf0e27edd98fe7516de7ea17f1b5254bcf7a00e`

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:

{
"api_key": "<secret-partner-api-key>",
"company_id": "<unique-company-id>",
"invoice_id": "<unique-invoice-id>",
"external_invoice_number": "<unique-partner-invoice-number>",
"payment_id": "<unique-payment-id>",
"payment_method": "ideal",
"payment_result": "authorized|cancelled"
}

get
Check status of a payment

https://app.clubcollect.com/api/v2/payments/:payment_id
ClubCollect will inform about any changes in the status using payment notifications. This endpoint can be used as a "backup" by the partner to check the current status of a payment in case any notification is dismissed.
Request
Response
Query Parameters
payment_id
required
string
Unique payment identifier returned by ClubCollect in the payment response.
company_id
required
string
Unique identifier of the company receiver of the payment.
signature
required
string
Should include `payment_id` and `company_id`
200: OK
When all the parameters are valid, the endpoint will return a JSON payload informing about the current status of the payment similar to the payload in the payment notifications.
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"invoice_id": "e06be9959a6d5ad6e1ce80caf97e3244d6024dd1",
"payment_id": "ae515fabdd886cd0c49408f9696c5498848977fe",
"payment_method": "ideal",
"payment_result": "authorized",
"external_invoice_number": "12345",
"created_at": "2019-09-15T16:15:56Z",
"updated_at": "2019-09-15T16:38:07Z",
}
422: Unprocessable Entity
When any of the parameters is invalid, the JSON payload will inform about the error.
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"error_code": "invalid_params",
"error_details": "invalid_payment_id"
}

get
Payment notifications feed

https://app.clubcollect.com/api/v2/payments/notifications
Returns a list containing the status of payments for a company, sorted from newest to oldest payments. It can be used by partners to catch up with notifications that might have been dismissed or not processed correctly.
Request
Response
Query Parameters
company_id
required
string
Unique identifier of the company.
signature
required
string
Should include `company_id` and `page`.
page
optional
string
Page number. If it's not given, default to 1. There are 25 payments per page.
200: OK
When all the parameters are valid, the endpoint will return a list of payments, sorted from newest to oldest.
[
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"invoice_id": "e06be9959a6d5a1ce80caf97e3244d6024dd1",
"payment_id": "ae515fabdd886cd0c49408f9696c5498848977fe",
"payment_method": "ideal",
"payment_result": "authorized",
"external_invoice_number": "12345",
"created_at": "2019-09-15T10:10:56Z",
"updated_at": "2019-09-15T10:16:08Z",
},
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"invoice_id": "c1d2753d2cb41989e2dff1c13b0281123b3d72a8",
"payment_id": "e382a785a3d8651f35a09b794ed0853c7451fad4",
"payment_method": "ideal",
"payment_result": "pending",
"external_invoice_number": "67890",
"created_at": "2019-09-15T16:15:56Z",
"updated_at": "2019-09-15T16:38:07Z",
},
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"invoice_id": "fe75927e05ed3f14db1bac824433dae78c0f362b",
"payment_id": "494f8b65497213aedbf88d1c5f690a6935c37362",
"payment_method": "ideal",
"payment_result": "cancelled",
"external_invoice_number": "78531",
"created_at": "2019-09-16T12:23:56Z",
"updated_at": "2019-09-16T13:39:07Z",
},
]
422: Unprocessable Entity
When one of the parameters is invalid, the JSON payload will inform about the error.
{
"company_id": "25b39de9bedc3409e195a99bb3a31918c12182e7",
"error_code": "invalid_params",
"error_details": "invalid_company_id"
}