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.
40014
400 Bad Request
Missing merchant data.
40015
400 Bad Request
The cardholder is invalid. Should contain no more than 21 characters.
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.
42201
422 Unprocessable Entity
Not properly configured gateway.
50001
500 Internal Server Error
Card tokenization error.

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
string(128)
ID of user.
id
string(19)
ID of transaction.
reference_id
string(19)
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) as string
Amount of virtual currency to give to a user.
price
decimal(12,4) as string
Price of transaction.
deposit
decimal(12,4) as string
Amount of deposit taken from this transaction.
earned
decimal(12,4) as string
Your revenue.
vat_rate
decimal(12,4) as string
VAT rate in country of payment.
vat_amount
decimal(12,4) as string
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.
type
string(16)
Type of callback. See the Callback types section.
status
string(16)
Status of a transaction. See the Callback statuses section.
reason
string(255)
May contain a reason for transaction.
sandbox
string(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 types

Type Description
transaction Fires if transaction status changes.

Callback statuses

Status Description
completed Transaction has completed successfully.
waiting_approval Transaction is waiting for approve.
processing Transaction is processing.
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.
refund_completed Transaction is reversed/refunded.
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.
payout_completed Payout is completed.
payout_failed Payout is failed.
payout_cancelled Payout is cancelled.
payout_abandoned Payout is abandoned.

Objects

Card-response object

Example object

{
    "lastFour": "1112",
    "mask": "************1112",
    "type": "visa",
    "scheme": "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). Deprecated: use scheme.
scheme
string
Card scheme (e.g. visa, mastercard).
expirationMonth
integer
Card expiration month.
expirationYear
integer
Card expiration year.

Card object

Example object

Parameter Description
number
string
PAN.
expiration_month
integer
Expiration month.
expiration_year
integer
Expiration year.
security_code
string
CVV.
holder
string
Cardholder.

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.

Payout-type object

Example object

{
    "id": 1,
    "key": "SEPA",
    "label": "Sepa"
}
Parameter Description
id
integer
Identifier of type.
key
string
Key of type.
label
string
Title of type.

Payout-parameter-control object

Example object

{
    "name": "description",
    "type": "text",
    "label": "Description",
    "required": false
}
Parameter Description
name
string
Parameter name key.
type
string
Data type of control.
label
string
Title of control.
required
boolean
Indicates whether parameter is required.

User object

Example object

{
    "id": 17,
    "identifier": "1",
    "displayName": "Username",
    "email": "test@example.com",
    "phone": "7777777777",
    "ip": "127.0.0.1",
    "locale": "ru"
}
Parameter Description
id
string
User id.
identifier
string
External user id.
displayName
string
Username.
email
string
User email.
phone
string
User phone number.
ip
string
User ip.
locale
string
User locale.

Flow

Payment 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 payment ​status​ is ​authenticating​:
    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. Merchant should check status of the payment;
  6. Merchant should check status of the payment;
  7. Status checking cases:
    • If ​status​ of payments is ​completed​ then merchant can provide a service to a user;
    • If ​status​ of payments is ​processing​ then merchant should recheck status of payment or wait for async callback;
  8. 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;
  9. 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;
  10. 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;
  11. 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.
  12. Merchant receives asynchronous ​callback​ with payment details and can provide a service to a user if status is completed.

Payout flow

  1. Merchant collects common payout parameters;
    • For payout to a card:
      • a) Merchant creates a temporary token and passes it in cardToken parameter at step 3;
      • b) Merchant passes a card number at step 3 in account parameter;
    • For non-card payout like wallet, SEPA, etc. then merchant passes recipient account in account parameter at step 3;
  2. Merchant requests required parameters for payout;
  3. Merchant creates payout with collected parameters.

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
optional
Email address of a user.
phone
optional
Phone number of a user in international 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.
ua
optional
User Agent string of a user. Max 255 symbols.
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,
    "orderId": "1",
    "success": true,
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "expirationMonth": 12,
        "expirationYear": 2034,
        "expiresAt": "2035-01-01T00:00:00+00:00",
        "holder": null,
        "scheme": "visa",
        "bankName": "EXTRAS TEST - VISA",
        "country": "US"
    },
    "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 or User object. See the Resolve user section.
card_token
required if card is empty
Token ID of a credit card. Can be ID of temporary or permanent token.
card
required if card_token is empty
Card object you can use without generation of 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
success
boolean
Indicates whether payment was successful. If acs object is present indicates whether payment process can be continued.
id
bigint
Identifier of a payment.
orderId
string
Merchant’s order ID.
referenceId
bigint
Reference transaction ID.
price
decimal
Integer or float number representing payment price.
currency
string
Three letter currency code in ISO 4217 format.
type
string
Transaction type (payment, payout, exchange).
status
string
Status of a current transaction.
fee
decimal
Merchant’s fee.
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.
createdAt
date(RFC3339)
Transaction created at.
updatedAt
date(RFC3339)
Transaction updated at.

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 process can be continued.
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,
    "orderId": "1",
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "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 request was successful.
orderId
string
Merchant’s order ID.
referenceId
bigint
Reference transaction ID.
price
decimal
Integer or float number representing payment price.
currency
string
Three letter currency code in ISO 4217 format.
type
string
Transaction type (payment, payout, exchange).
status
string
Status of a current transaction.
fee
decimal
Merchant’s fee.
card
object
Card object
user User.

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,
    "id": 1326123574311498453,
    "orderId": "1",
    "referenceId": null,
    "price": "5.99",
    "fee": "0.0000",
    "currency": "USD",
    "type": "payment",
    "status": "completed",
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "User",
        "email": "user@example.com",
        "phone": "11111111111",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "card": {
        "lastFour": "1112",
        "mask": "************1112",
        "expirationMonth": 12,
        "expirationYear": 2034,
        "expiresAt": "2035-01-01T00:00:00+00:00",
        "holder": null,
        "scheme": "visa",
        "bankName": "EXTRAS TEST - VISA",
        "country": "US"
    }
}

Reverses a completed payment transaction.

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 request was successful.
id
bigint
Identifier of a payment.
orderId
string
Merchant’s order ID.
referenceId
bigint
Reference transaction ID.
price
decimal
Integer or float number representing payment price.
currency
string
Three letter currency code in ISO 4217 format.
type
string
Transaction type (payment, payout, exchange).
status
string
Status of a current transaction.
fee
decimal
Merchant’s fee.
card
object
Card object
user User.

Create new transaction

Example Request

curl https://api.crassula.io/v1/transaction/create \
    -d signature=efe4077d4ea0d62fd62b65f1969184c048880183e9a342dd46e2101ff93b538a \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d user=1 \
    -d payment_method=web_money_wmz \
    -d price=5.99 \
    -d currency=USD \
    -d description=Test \
    -d success_url=https://example.com \
    -d fail_url=https://example.com

Example Response

{
    "id": "1530105654244093715",
    "amount": 5.99,
    "currency": "USD",
    "status": "opened"
}

Redirect user to https://checkout.crassula.io/confirm/{id}/ to continue with confirmation on the payment system side.

HTTP request

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

Request parameters

Parameter Description
project
required
Public key of your project.
user
required
Unique and unchangeable identifier of a user.
display_name
optional
Full name or nickname of a user.
payment_method
required
Key of a payment method. Possible values are: paypal, qiwi, yandex_money_wallet, yandex_money_wallet_v2, web_money_wme, web_money_wmz, web_money_wmr.
price
required
Integer or decimal number representing payment amount.
currency
required
Three letter currency code in ISO 4217 format.
email
optional
Email address of a user.
ip
optional
IP address of a user.
ua
optional
User Agent string of a user. Max 255 symbols.
phone
optional
Phone number of a user in international format, without the leading + and any separators. Required for “qiwi” payment method.
locale
optional
Locale of a user in ISO 639-1 format.
order_id
optional
Merchant’s order ID that will be returned back in a callback.
description
required
String describing reversal reason.
success_url
required
URL where to redirect user on success.
fail_url
required
URL where to redirect user on fail.
signature
required
See the Authentication section.

Returns

Parameter Description
id
string
Identifier of a transaction.
amount
float
Integer or float number representing an amount.
currency
string
Three letter currency code in ISO 4217 format.
status
string
Status of a current transaction.

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":"payment",
    "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

Type Description
deposit Funds are charged from the merchant.
payment Funds are charged from a user.
verification Verification transaction.
chargeback Chargeback of payment transaction. Funds are returned to a user. Penalty may apply.
refund Refund of payment 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.
exchange Exchange transaction.
payout Payout transaction.
settlement Settlement transaction.
penalty Penalty transaction.
rolling_reserve Rolling reserve transaction.

Transaction statuses

Status Description
opened Transaction is opened.
processing Transaction is processing.
waiting_approval Transaction is waiting for approve.
authenticating Transaction is authenticating.
authorized Transaction is authorized.
completed Transaction has completed successfully.
failed Transaction has failed.
cancelled Transaction has cancelled.
abandoned Transaction has abandoned.
refunded Transaction is reversed/refunded.
charged_back Chargeback has completed because of a started dispute.
retrieved Chargeback dispute is won. Funds taken with a chargeback are returned.
returned Returned rolling reserve.
verified Transaction is of type verification and has completed successfully. Funds in amount of 1 EUR were frozen and released to verify card.

Payout

Fetch available payout types

Example Request

curl https://api.crassula.io/v1/payout-types?\
    project=d55ad89070d6172cc0eeeecfdde2c554

Example of Complete Response

{
   "success": true,
   "types": [
      {
         "id": 0,
         "key": "CREDIT_CARD",
         "label": "Credit Card"
      },
      {
         "id": 1,
         "key": "SEPA",
         "label": "Sepa"
      }
   ]
}

List of available payout types for merchant

HTTP request

GET https://api.crassula.io/v1/payout-types

Request parameters

Parameter Description
project
required
Public key of your project.

Returns

Parameter Description
success
boolean
Indicates request was successful or not.
types
object
Collection of payout type. See Payout-type object for details.

Fetch payout parameters

Example Request

curl https://api.crassula.io/v1/payout-parameters?\
    project=d55ad89070d6172cc0eeeecfdde2c554&\
    type=0&\
    currency=RUB&\
    account=553691

Example of Complete Response

[
    {
        "name": "amount",
        "type": "text",
        "label": "Amount",
        "required": true
    },
    {
        "name": "phone",
        "type": "text",
        "label": "Phone",
        "required": true
    },
    {
        "name": "description",
        "type": "text",
        "label": "Description",
        "required": false
    }
]

List of required parameters. Payout parameters depend on (project, type, account, currency). This parameter names will be used in payout.

HTTP request

GET https://api.crassula.io/v1/payout-parameters

Request parameters

Parameter Description
project
required
Public key of your project.
type
required
Id of Payout-type object. For fetch use Fetch available payout types
account
required
Recipient’s account. If payout type equals to CREDIT_CARD then pass BIN (first 6 digit of credit card) otherwise pass it entirely.
currency
required
Three letter currency code in ISO 4217 format.

Returns

Response will contain collection of Payout-parameter-control object.

Payout parameters

These are all available payout parameters. Use the method Fetch payout parameters to acquire the required additional parameters for your use case.

Parameter Description
firstName Remitter First Name.
lastName Remitter Last Name.
birthDate Remitter Birth Date (d.m.Y).
birthPlace Remitter Birth Date (d.m.Y).
country Remitter Country.
countryOfCitizenship Remitter Country Of Citizenship.
city Remitter City.
address Remitter Address.
postalCode Remitter Postal Code.
documentType Remitter Document Type. (passport, id)
documentIssuer Remitter Document Issuer.
documentSeries Remitter Document Series.
documentNumber Remitter Document Number.
documentIssuedAt Remitter Document Issued At.
documentValidUntil Remitter Document Valid Until.
remitterCardNumber Remitter Card Number.
remitterCardToken Remitter Card Token.
remitterCardExpirationMonth Remitter Card Token.
remitterCardExpirationYear Remitter Card Token.
remitterPhone Remitter Phone.
beneficiaryFirstName Beneficiary first name.
beneficiaryLastName Beneficiary Last Name.
beneficiaryLegalName Beneficiary Legal Name.
beneficiaryDocumentType Beneficiary Document Type. (passport, id)
beneficiaryDocumentIssuer Beneficiary Document Issuer.
beneficiaryDocumentSeries Beneficiary Document Series.
beneficiaryDocumentNumber Beneficiary Document Number.
beneficiaryDocumentIssuedAt Beneficiary Document Issued At.
beneficiaryDocumentValidUntil Beneficiary Document Valid Until.
cardExpirationDate Card Expiry date MM/YY. If required you have to pass it to cardToken.
description Description of payout transaction.
phone Phone Number.
cardHolder Card Holder.
fullName Full Name.
receiverBankBIC Bic/Swift.

Create payout

Example Request

curl https://api.crassula.io/v1/payout \
    -d signature=8bcfd8f3056bdb00d5dc84ed4d6ae7b6198b64f5a36d4e82f5c9ebca52be4b40 \
    -d project=d55ad89070d6172cc0eeeecfdde2c554 \
    -d type=0 \
    -d currency=RUB \
    -d amount=10 \
    -d description=payout \
    -d cardToken=4f2bb447726f0e759696c495024d6fda7706ca5b87eed431867f3f5410767a5f \
    -d phone=77777777777

Example of Complete Response

{
    "id": "1534974617313178347",
    "status": "processing",
    "success": true
}

Create new payout

HTTP request

POST https://api.crassula.io/v1/payout

Common request parameters

Parameter Description
project
required
Public key of your project.
type
required
Id of Payout-type object. For fetch use Fetch available payout types.
account
optional
Recipient’s account. Mostly required, but if payout type is CREDIT_CARD then account or cardToken can be used.
cardToken
optional
Token of a credit card. Can be used instead of passing card number to account. See create card token.
amount
required
Integer or float number representing payout price.
currency
required
Three letter currency code in ISO 4217 format.
orderId
optional
Merchant’s order ID.
signature
required
Make sure that the signature sent with the callback is correct. See the Authentication section.

Each combination of payout type, account and currency may have it’s own list of additional parameters required to complete the payout, thus you have to acquire the list of required additional parameters using the method Fetch payout parameters. For all possible payout parameters, please consult Payout parameters.

Returns

Parameter Description
id
bigint
Identifier of a payment.
success
boolean
Indicates whether request was successful or not.
status
string
Status of a transaction. See the Callback statuses section.

Balance

Get merchants balance

Example Request

curl https://api.crassula.io/v1/balance?\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    currency=USD\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "amount":"100.00",
    "rolling_reserve":"0.20",
    "currency":"USD",
    "base_amount":"1286.27",
    "base_rolling_reserve":"0.00"
}

Get merchants balance by currency

HTTP request

GET https://api.crassula.io/v1/balance

Request parameters

Parameter Description
project
required
Public key of your project.
currency
string(3)
Currency.
signature
required
See the Authentication section.

Returns

Parameter Description
amount
string
Available amount for operation.
rolling_reserve
string
Rolling reserve.
currency
string
Currency of balance.
base_amount
string
Total amount in base currency.
base_rolling_reserve
string
Base rolling reserve.

Transactions

Get transaction by id

Example Request

curl https://api.crassula.io/v1/transactions/1569310086280783205?\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "id": "1569310086280783205",
    "orderId": "qwery12345",
    "referenceId": null,
    "price": "150.00",
    "fee": "0.0000",
    "currency": "RUB",
    "type": "payment",
    "status": "refunded",
    "method": "yandex_money",
    "originalStatus": "completed",
    "user": {
        "id": 17,
        "identifier": "1",
        "displayName": "LuxeMate",
        "email": "user@example.com",
        "phone": "7777777777",
        "ip": "127.0.0.1",
        "locale": "ru"
    },
    "createdAt": "2017-05-08T11:08:26+00:00",
    "updatedAt": "2017-05-08T11:08:34+00:00",
    "reason": null
}

Get transactions by order id

HTTP request

GET https://api.crassula.io/v1/transactions/{id}

Request parameters

Parameter Description
id
required
Transaction id.
project
required
Public key of your project.
signature
required
See the Authentication section.

Returns

Parameter Description
id
bigint
Identifier of a payment.
orderId
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.
method
string
Payment method.
status
string
Status of transaction including all other transaction effects (e.g. opened, completed, charged_back, refunded).
originalStatus
string
Original status of transaction. The last status applied to a transaction itself (e.g. opened, authenticating, completed).
createdAt
date in ISO 8601
Date when transaction was created.
updatedAt
date in ISO 8601
Date when transaction was last updated (doesn’t include other transaction effects).
user User.
card User’s card.

Get transactions by order id

Example Request

curl https://api.crassula.io/v1/transactions?\
    orderId=d55ad89070d6172cc0eeeecfdde2c554\
    project=d55ad89070d6172cc0eeeecfdde2c554\
    signature=d0aeccdcf5f66e8464ed584e50528530967cb7ef8a76e26935f8b3fafd3c634b

Example of Complete Response

{
    "totalCount": 1,
    "transactions": [
        {
            "id": "1569310086280783205",
            "orderId": "qwery12345",
            "referenceId": null,
            "price": "150.00",
            "fee": "0.0000",
            "currency": "RUB",
            "type": "payment",
            "status": "refunded",
            "method": "yandex_money",
            "originalStatus": "completed",
            "user": {
                "id": 17,
                "identifier": "1",
                "displayName": "LuxeMate",
                "email": "user@example.com",
                "phone": "7777777777",
                "ip": "127.0.0.1",
                "locale": "ru"
            },
            "createdAt": "2017-05-08T11:08:26+00:00",
            "updatedAt": "2017-05-08T11:08:34+00:00",
            "reason": null
        }
    ]
}

Get transactions by order id

HTTP request

GET https://api.crassula.io/v1/transactions

Request parameters

Parameter Description
orderId
required
Merchant’s order id.
project
required
Public key of your project.
signature
required
See the Authentication section.
status
string
Filter by transaction status.
type
string
Filter by transaction type.
created[from]
string
Filter transaction created after.
created[to]
string
Filter transaction created before.
updated[from]
string
Filter transaction updated after.
updated[to]
string
Filter transaction updated before.
page
string
Page number.
limit
string
Set limit transaction on page.

Returns

Parameter Description
totalCount
int
Count of available transaction in the response.
transactions
Object
Collection of transaction. Structure of transaction you can see in Transaction response section.