NAV
curl

Authentication

Example of function to generate a signature in PHP:

<?php

function generate(array $parameters)
{
    sort($parameters, SORT_STRING);

    return hash_hmac('sha256', join('|', $parameters), 'PRIVATE_KEY');
}

Request and callback parameters are signed to make sure the values won’t be changed.

Rules to generate a signature:

  1. Sort parameter values ascending by value (case sensitive);
  2. Concatenate parameter values with a pipe (e.g. n3rf34j96j8rge4|123|example@example.com);
  3. Hash it with a HMAC­SHA256 algorithm.

Errors

Error Example

{
    "error": {
        "code": 40401,
        "message": "Project's public key is missing."
    }
}
Code Message
40001
400 Bad Request
Project’s public key is missing.
40002
400 Bad Request
User’s identifier is missing.
40003
400 Bad Request
The credit card number is missing.
40004
400 Bad Request
The credit card number is invalid.
40005
400 Bad Request
The expiry is invalid.
40006
400 Bad Request
The credit card security code is missing.
40007
400 Bad Request
The credit card security code is invalid.
40008
400 Bad Request
Credit card token is missing.
40009
400 Bad Request
Credit card data is missing.
40010
400 Bad Request
User’s email is missing.
40011
400 Bad Request
User’s IP address is missing.
40012
400 Bad Request
The credit card expiration month is missing.
40013
400 Bad Request
The credit card expiration year is missing.
40101
401 Unauthorized
Signature is missing.
40102
401 Unauthorized
Authentication token is missing.
40301
403 Forbidden
Signature is invalid.
40302
403 Forbidden
Authentication token is invalid.
40303
403 Forbidden
Authentication token has expired.
40304
403 Forbidden
Credit card token has expired.
40305
403 Forbidden
Credit card token is already used.
40306
403 Forbidden
Platform authentication token is invalid.
40307
403 Forbidden
Platform authentication token is invalid.
40308
403 Forbidden
User is blocked.
40309
403 Forbidden
Credit card is blocked.
40310
403 Forbidden
Recurring is disabled for requested user.
40311
403 Forbidden
Recurring expired for requested user.
40312
403 Forbidden
Card remembering is disabled for project.
40401
404 Not Found
Project is missing.
40402
404 Not Found
Credit card token is invalid.
40403
404 Not Found
Transaction does not exist.
40404
404 Not Found
Platform is missing.
40405
404 Not Found
Reference recurrent transaction is missing.
40406
404 Not Found
User is missing.
40407
404 Not Found
Platform user is missing.
40501
405 Method Not Allowed
Transaction is already completed.
40502
405 Method Not Allowed
Recurring payments are too frequent for requested user.
40503
405 Method Not Allowed
Unable to create recurrent transaction.
40504
405 Method Not Allowed
Transaction cannot be reversed.

Callbacks

Example Request

curl CALLBACK_URL \
    -d signature=ea7379f5f09cef58e61afccf7eb73d6963ef286f96821cbfa8f2377076e5c59a \
    -d project=13 \
    -d user=47055 \
    -d id=1462905107214034164 \
    -d reference_id= \
    -d order_id= \
    -d amount=200 \
    -d price=1.99 \
    -d deposit=0 \
    -d earned=1.99 \
    -d vat_rate=18 \
    -d vat_amount=0.3035 \
    -d currency=USD \
    -d status=completed \
    -d sandbox=1 \
    -d attr_one=1 \
    -d attr_two="Hello world"

Callback URL can be set in project settings. You will receive the callback parameters via HTTP POST method. All parameters below are present in a request, but can be empty. When calculating a signature all parameter values must be treated as strings.

Parameter Description
project
integer(11)
ID of your project.
user
integer(11)
ID of user.
id
bigint(20)
ID of transaction.
reference_id
bigint(20)
ID of a parent transaction. For example, in refund_completed callback it’ll be equal to an ID of transaction that is being refunded.
order_id
string(64)
Your order ID, if it was provided.
amount
decimal(9,2)
Amount of virtual currency to give to a user.
price
decimal(12,4)
Price of transaction.
deposit
decimal(12,4)
Amount of deposit taken from this transaction.
earned
decimal(12,4)
Your revenue.
vat_rate
decimal(12,4)
VAT rate in country of payment.
vat_amount
decimal(12,4)
Calculated VAT amount. VAT is calculated from price, but is not subtracted from your earnings.
currency
string(3)
Currency of transaction. Price, deposit and earned parameters are in this currency.
status
string(16)
Status of a transaction. See the Callback statuses section.
sandbox
integer(1)
Represents your project’s state. Equals 1 if in sandbox, 0 otherwise.
attr_*
string
Any custom attributes, that were used to create a payment. For example: attr_realm, attr_server, attr_landing.
signature
string(64)
Make sure that the signature sent with the callback is correct. See the Authentication section.

Callback statuses

Status Description
completed Transaction has completed successfully.
failed Transaction has failed.
verified Transaction is of type verification and has completed successfully. Funds in amount of 1 EUR were frozen and released to verify card.
reversed Transaction is reversed before payout.
refund_completed Transaction is reversed/refunded after payout.
chargeback_completed Chargeback has completed because of a started dispute.
retrieval_completed Chargeback dispute is won. Funds taken with a chargeback are returned.
penalty_completed Penalty amount applied to transactions of type refund or chargeback.

Objects

Card object

Example object

{
    "lastFour": "1112",
    "mask": "************1112",
    "type": "visa",
    "expirationMonth": 4,
    "expirationYear": 2020
}
Parameter Description
lastFour
string
Last four digits of a card number.
mask
string
Card number mask. Only last four digits are visible, others are hidden with asterisks.
type
string
Card type (e.g. visa, mastercard).
expirationMonth
integer
Card expiration month.
expirationYear
integer
Card expiration year.

ACS object

Example object

{
    "url": "https://bank.example.com/ACS/",
    "parameters": {
         "MD": "eyJ0cmFuc2Fj...",
         "PaReq": "eJxdUWF...",
         "TermUrl": "https://example.com/acs_return/"
    }
}
Parameter Description
url
string
URL where user must be redirected using HTTP POST with each parameter from parameters object.
parameters
object
Parameters (PaReq, MD, TermUrl) that must be passed to ACS. url ​as­is using the HTTP POST method.

Recurring object

Example object

{
     "frequency": 1,
     "endsAt": "2015­10­22T11:49:23+03:00"
}
Parameter Description
frequency
integer
Minimal number of days between recurring payments.
endsAt
date in ISO 8601 format
Last date when repeated payments will be available for a user.

Flow

  1. User inputs and submits card data;
  2. Merchant creates a temporary token for ​10 minutes​ via JSONP or AJAX;
  3. Merchant receives temporary token and other payment data on a server-side;
  4. Merchant charges a card;
  5. If ​success​ is ​true​ and ​acs object​ is returned:
    1. Merchant POSTs ​acs.parameters​ to ​acs.url in a web browser;
    2. User inputs and submits his 3DSecure password;
    3. ACS. POSTs parameters (PaRes, MD) back to merchant’s ​acs_return_url​;
    4. Merchant authenticates a card;
    5. If ​success​ is ​true​ then merchant can provide a service to a user;
  6. If ​success​ is ​true​ and ​​acs object is not returned then merchant can provide a service to a user;
  7. If ​remember​ was equal to 1, merchant will receive a ​permanentToken​ parameter when charging or authenticating a card. You can use ​permanent token without requiring a user to input card data again;
  8. If ​recurring​ was equal to 1, merchant will receive a recurring object, containing allowed recurring frequency and ending date. Merchant can make payments for a user using manual recurring;
  9. If ​verify_card​ was equal to 1, then transaction price will be set to 1 EUR, that will be put on hold and then instantly returned;
  10. verify_card​ can be effectively used with ​recurring, recurring_interval, recurring_trial​ or remember​ parameters as it checks the validity of a card via freezing and releasing funds on a card.
  11. Merchant receives asynchronous ​callback​ with payment details and can provide a service to a user if status is completed.

User

Resolve a user

Example Request

curl https://api.crassula.io/v1/user/resolve \
    -d signature=135ef9ee89f1f1addc43211b70ff4d3a976ac44ff56b7470c178618f6f19c204 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d identifier=1 \
    -d display_name="Example User" \
    -d email="user@example.com" \
    -d phone=123456789 \
    -d locale=en \
    -d ip=127.0.0.1

Example Response:

{
    "id": 47055
}

Returns internal user ID. Creates a user if it doesn’t exist or returns an ID of existing user.

HTTP request

POST https://api.crassula.io/v1/user/resolve

Request parameters

Parameter Description
project
required
Public key of your project.
identifier
required
Unique and unchangeable identifier of a user.
display_name
optional
Full name of nickname of a user.
email
required
Email address of a user.
phone
optional
Phone number of a user in internationa format, without the leading + and any separators.
locale
optional, default is project’s locale
Locale of a user in ISO 639-1 format.
ip
required
IP address of a user.
signature
required
See the Authentication section.

Change recurring settings

Example Request

curl https://api.crassula.io/v1/user/changeRecurring \
    -d signature=0da5b5a9165343d4de8073aaf91bc594e5fad7ef448202fdc688914168eaf658 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d interval=30 \
    -d price=3.50 \
    -d currency=USD

Example Response:

{
    "success": true
}

Changes recurring settings of a user.

HTTP request

POST https://api.crassula.io/v1/user/changeRecurring

Request parameters

Parameter Description
project
required
Public key of your project.
user
required
ID of internal user. See the Resolve user section.
interval
optional
Days between repeated payments. When set to 0, only manual recurring remains available.
price
optional
Price of repeated payments.
currency
required if price is present
Currency of repeated payments.
signature
required
See the Authentication section.

Returns

Parameter Description
success
boolean
Indicates whether change was successful.

Cancel recurring

Example Request

curl https://api.crassula.io/v1/user/cancelRecurring \
    -d signature=814c669f58d48f91837591b59ca2f8ac3186c3d69081361bece6188299ba14a9 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055

Example Response:

{
    "success": true
}

Cancels repeated payments of a user.

HTTP request

POST https://api.crassula.io/v1/user/cancelRecurring

Request parameters

Parameter Description
project
required
Public key of your project.
user
required
ID of internal user. See the Resolve user section.
signature
required
See the Authentication section.

Returns

Parameter Description
success
boolean
Indicates whether cancellation was successful.

Card

Create a token

Example Request

curl "https://api.crassula.io/v1/card/getToken?\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    number=4012001037141112&\
    expiration_month=4&\
    expiration_year=2020&\
    security_code=123"

Example Response:

{
    "id": "11fe4b4d430eccc4ca59b8df31bc5d161b4d54020082362a7d389486f5349066",
    "expiresAt": "2015­05­22T11:21:37+03:00",
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
}

Example response using JSONP callback:

myCallback({
    "id": "11fe4b4d430eccc4ca59b8df31bc5d161b4d54020082362a7d389486f5349066",
    "expiresAt": "2015­05­22T11:21:37+03:00",
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
})

Stores card data into a vault and returns created temporary token ID. You can use token id to securely Charge a card.

HTTP request

GET https://api.crassula.io/v1/card/getToken

Query parameters

Parameter Description
project
required
Public key of your project.
number
required
Card number without any separators.
expiration_month
required
Integer representing the card’s expiration month.
expiration_year
required
Four digit number representing card’s expiration year.
security_code
required
Card security code (CVC, CVV2).
callback
optional
Callback function name for JSONP.

Returns

Parameter Description
id
string
Identifier of a token.
expiresAt
date in ISO 8601 format
Date when token expires.
card
object
Card object

Payment

Charge a card

Example Request

curl https://api.crassula.io/v1/card/process \
    -d signature=129a12c0acb47b0b5c7a76f441070c5cfac495de40cc9520f0e9f07120f1b455 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d card_token=d5c83ed1575b6fa30e8b977016c75a5417c5c9d34930d7076e9e36f374577345 \
    -d price=5.99 \
    -d currency=USD \
    -d description="My custom description." \
    -d acs_return_url="https://example.com/acs_return/" \
    -d attr_product_id=123

Example of Complete Response

{
    "id": 1326123574311498453,
    "success": true,
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    },
    "acs": {
        "url": "https://bank.example.com/ACS/",
        "parameters": {
             "MD": "eyJ0cmFuc2Fj...",
             "PaReq": "eJxdUWF...",
             "TermUrl": "https://example.com/acs_return/"
        }
    },
    "permanentToken": "d5c83ed1575b6fa30e8b977016c75a5417c5c9d34930d7076e9e36f374577345",
    "recurring": {
         "frequency": 1,
         "endsAt": "2015­10­22T11:49:23+03:00"
    }
}

Charges a card for certain amount of currency.

HTTP request

POST https://api.crassula.io/v1/card/process

Request parameters

Parameter Description
project
required
Public key of your project.
user
required
ID of internal user. See the Resolve user section.
card_token
required
Token ID of a credit card. Can be ID of temporary or permanent token.
price
required
Integer or float number representing payment price.
currency
required
Three letter currency code in ISO 4217 format.
order_id
optional
Merchant’s order ID that will be returned back in a callback. string(64)
description
required
Description of a payment.
3ds
optional, default is 0
Allows to switch payment processing to 3D Secure mode. Only works if 3D Secure is not forced for particular project.
acs_return_url
optional
URL where ACS will return user after the 3D Secure authentication. See Authenticate a card section for next steps.
remember
optional, default is 0
Integer (1 or 0) that indicates whether user wants to remember his credit card in your service. If 1, then ​permanentToken​ in response will contain token ID, that is used to .
verify_card
optional, default is 0
Use it to create a permanent token or setup repeated payments (recurring). If set to 1, then 1 EUR on user’s card will be frozen and released instantly.
recurring
optional, default is 0
Indicates whether a user wants to subscribe to recurring payments.
recurring_interval
required if recurring is set to 1
Days between repeated payments. When set to 0, only manual recurring remains available.
recurring_trial
optional, default is 0
Trial period in days before starting repeated payments. First repeated payment will occur after trial period.
attr_*
optional
Any custom attributes, that you want to be returned in a callback. For example: attr_realm, attr_server, attr_landing.
signature
required
See the Authentication section.

Returns

Parameter Description
id
bigint
Identifier of a payment.
success
boolean
Indicates whether payment was successful. If acs object is present indicates whether payment process can be continued.
card
object
Card object
acs
object
If this object is present, then card is enrolled for 3DSecure and it is required to redirect user to ACS.. See ACS object for details.
permanentToken
string, default is null
ID of a permanent card token. Permanent card token is used to charge a card without requesting card data again. Although card data is not required, it’s still required to go through 3DSecure authentication.
recurring
object
If this object is present, then user is enrolled to repeated payments. Repeated payments do not require 3DSecure authentication, unlike permanent tokens. See Recurring object for details.

Authenticate a card

Example of Complete Response

{
    "id": 1326123574311498453,
    "success": true,
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    },
    "permanentToken": "9a083895d07ca58f6e5505bd19ed35ca9a083895d07ca58f6e5505bd19ed35ca",
    "recurring": {
         "frequency": 1,
         "endsAt": "2015­10­22T11:49:23+03:00"
    }
}

Authenticates a card using PaRes and MD parameters POST'ed back to acs_return_url from ACS.

HTTP request

POST https://api.crassula.io/v1/card/authenticate

Request parameters

Parameter Description
project
required
Public key of your project.
PaRes
required
Payer authentication response.
MD
required
Merchant data.
signature
required
See the Authentication section.

Returns

Parameter Description
id
bigint
Identifier of a payment.
success
boolean
Indicates whether payment was successful.
card
object
Card object
permanentToken
string, default is null
ID of a permanent card token. Permanent card token is used to charge a card without requesting card data again. Although card data is not required, it’s still required to go through 3DSecure authentication.
recurring
object
If this object is present, then user is enrolled to repeated payments. Repeated payments do not require 3DSecure authentication, unlike permanent tokens. See Recurring object for details.

Manual recurring

Example Request

curl https://api.crassula.io/v1/card/processRecurring \
    -d signature=84d134b2d662777a7f9ac0256375582742c85f7de9b95ebda4c54826f78290e5 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=47055 \
    -d price=5.99 \
    -d currency=USD \
    -d order_id=12345 \
    -d description="My custom description."

Example Response

{
    "id": 1326123574311498453,
    "success": true,
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "type": "visa",
        "expirationMonth": 4,
        "expirationYear": 2020
    }
}

Charges a user subscribed to repeated payments out of interval. Useful for automatic balance top up in certain services.

HTTP request

POST https://api.crassula.io/v1/card/processRecurring

Request parameters

Parameter Description
project
required
Public key of your project.
user
required
ID of internal user. See the Resolve user section.
price
required
Integer or float number representing payment price.
currency
required
Three letter payment currency code in ISO 4217 format.
order_id
optional
Merchant’s order ID that will be returned back in a callback. string(64)
description
optional
Description of a payment.
signature
required
See the Authentication section.

Returns

Parameter Description
id
bigint
Identifier of a payment.
success
boolean
Indicates whether payment was successful.
card
object
Card object

Reverse a payment

Example Request

curl https://api.crassula.io/v1/transaction/reverse \
    -d signature=7f9a1409ee03da997dbd4bcc40066cd7ea58b12f41203471e67fcf477c9bca31 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d id=1226123574311498453 \
    -d amount=5.99 \
    -d comment="Suspected fraud."

Example Response

{
    "success": true
}

Reverses a payment transaction if reverse is being made before payout or creates a refund transaction if payout was made already.

HTTP request

POST https://api.crassula.io/v1/transaction/reverse

Request parameters

Parameter Description
project
required
Public key of your project.
id
optional, either id or order_id is required
Identifier of a payment to reverse.
order_id
optional, either order_id or id is required
Merchant’s order ID.
amount
required
Integer or float number representing an amount to reverse.
comment
optional
String describing reversal reason.
signature
required
See the Authentication section.

Returns

Parameter Description
success
boolean
Indicates whether reversal was successful.

Retrieve status of a transaction

Example Request

curl "https://api.crassula.io/v1/transaction/status?\
    signature=06c4f84b49c3b42d6f4fb0486408f276b634bb97ec3c86a643aa64285cd841ed&\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    id=1472169801800314651"

Example Response

{
    "id":"1472169801800314651",
    "order_id":null,
    "price": 20,
    "fee": 0,
    "currency": "USD",
    "type":"deposit",
    "status":"refunded",
    "original_status":"completed",
    "created_at":"2016-08-26T03:03:21+03:00",
    "updated_at":"2016-08-26T03:03:22+03:00"
}

Returns transaction details and status.

HTTP request

GET https://api.crassula.io/v1/transaction/status

Request parameters

Parameter Description
project
required
Public key of your project.
id
optional, either id or order_id is required
Identifier of a transaction.
order_id
optional, either order_id or id is required
Merchant’s order ID.
signature
required
See the Authentication section.

Returns

Parameter Description
id
bigint
Identifier of a payment.
order_id
string
Merchant’s order ID.
price
decimal(12,2)
Price of transaction.
fee
decimal(12,4)
Merchant’s fee.
currency
string
Currency of transaction.
type
string
Type of transaction.
status
string
Status of transaction including all other transaction effects (e.g. opened, completed, charged_back, refunded).
original_status
string
Original status of transaction. The last status applied to a transaction itself (e.g. opened, authenticating, completed).
created_at
date in ISO 8601
Date when transaction was created.
updated_at
date in ISO 8601
Date when transaction was last updated (doesn’t include other transaction effects).

Transaction types

Status Description
deposit Funds are charged from a user.
refund Refund of deposit transaction. Funds are returned to a user. Penalty may apply.
chargeback Chargeback of deposit transaction. Funds are returned to a user. Penalty may apply.
retrieval Retrieval of chargeback transaction. Funds are returned to merchant. Penalty may not be returned back.

Transaction statuses

Status Description
completed Transaction has completed successfully.
failed Transaction has failed.
verified Transaction is of type verification and has completed successfully. Funds in amount of 1 EUR were frozen and released to verify card.
reversed Transaction is reversed before payout.
refunded Transaction is reversed/refunded after payout.
charged_back Chargeback has completed because of a started dispute.
retrieved Chargeback dispute is won. Funds taken with a chargeback are returned.