PSP – documentation

Payment flow

User inputs and submits card data
Merchant creates a payment
If payment status is authenticating:
- Merchant POSTs acs.parameters to acs.url in a web browser
- User inputs and submits his 3DSecure password
- ACS POSTs parameters (PaRes, MD) back to merchant’s acsReturnUrl
- Merchant authenticates a card
If payment status is waiting:
- If there is a redirect property in the answer, Merchant POSTs (or GETs, depending on method property) redirect.parameters.data to redirect.url in a web browser. Parameter redirect.parameters.data is a string with GET or POST request parameters, for example, param1=value1&param2=value2. Values are Url-encoded.
- If the response contains the p2p property, the Merchant displays its own checkout form using the data from the p2p properties
- Merchant checks status of the payment and/or wait for callback
Merchant should check status of the payment
Status checking cases:
- If status of the payment is paid then merchant can provide a service to a user
- If status of the payment is processing then merchant should recheck status of payment or wait for async callback
Merchant receives asynchronous callback with payment details and can provide a service to a user if status is paid

Payout flow

Merchant process a payout payment
If payment status is waiting, merchant should check status of the payment (final payout statuses are handled and error)
or wait for async callback for statuses (final payout statuses are paid or failed)

Callbacks

Callback URL can be set in project settings. You will receive the callback parameters via HTTP POST method with Content-Type: application/x-www-form-urlencoded header. All parameters below are present in a request, but can be empty. When calculating a signature all parameter values must be treated as strings.

If the callback URL replies with an HTTP status other than 200, 5 more attempts will be made, adding one minute to the interval each time.

Parameter	Description
project string	ID of your project.
userId string	ID of user.
invoiceId string	ID of created invoice. For each passed orderId we create a new invoice
transactionId string	ID of invoice transaction.
orderId string	Your order ID.
amount decimal	Amount of invoice.
currency string	Currency of invoice. Amount is in this currency.
type string	Type of callback (payment, refund, payout).
status string	Status of a transaction (paid, failed, refunded).
sandbox bool	Represents your project’s state. Equals True if in sandbox, False otherwise.
message string	Success or decline message from acquirer
userParam1.....userParamN string	Custom attributes passed to userData, that you want to be returned in a callback. For example: account, server etc..
signature string	Make sure that the signature sent with the callback is correct. See the Authentication section.


Example:

curl CALLBACK_URL \
    -d signature=ea7379f5f09cef58e61afccf7eb73d6963ef286f96821cbfa8f2377076e5c59a \
    -d project=209E6150-8948-4FED-9F54-94A000A452B9 \
    -d userId=47055 \
    -d invoiceId=4435564343 \
    -d transactionId=1462905107214034164 \
    -d orderId=123 \
    -d amount=1.99 \
    -d currency=USD \
    -d type=payment \
    -d status=paid \
    -d sandbox=True \
    -d message="Success payment" \
    -d account=535235 \
    -d group="VIP"

Test cards

Test cards are accepted only when project is in sandbox state.

Expiration date must be grater than the current month. Any security code is valid.

4030184432938262 - successfully authorization
4565895344850450 - payment declined
4639782332209752 - successfully authorization after 3ds secure
4103665377096761 - payment declined after 3ds secure
5153914875489128 - redirect with GET method
5188015971789434 - redirect with POST method

4013514229204869 - success payout
5853424554596047 - waiting payout

API

URL: https://trustfastpay.com
All POST requests must have "application/json" content type.

Authentication

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

Rules to generate a signature:

1. Sort not-null and not-empty parameter values ascending by value (case sensitive). If you use userData, do not forget to add it ;
2. Concatenate parameter values with a pipe (e.g. 123|example@example.com|n3rf34j96j8rge4);
3. Hash it with a HMACSHA256 algorithm.

Decimal values must be rounded to two decimal places. The fractional part must be separated by a dot. Example: 1.00 .


    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');
    }

    ?>

    Replace PRIVATE_KEY from example with your project’s private key.

Errors

Code	Message
40001	Project's public key is missing.
40002	User's identifier is missing.
40003	The credit card number is missing.
40004	The credit card number is invalid.
40005	The expiry is invalid.
40006	The credit card security code is missing.
40007	The credit card security code is invalid.
40008	Credit card token is missing.
40009	Credit card data is missing.
40010	User's email is missing.
40011	User's IP address is missing.
40012	The credit card expiration month is missing.
40013	The credit card expiration year is missing.
40015	The cardholder is invalid. Should contain letters only no more than 21 characters.
40050	This transaction is not related to the requested project.
40051	This transaction is not related to the requested order.
40052	Incorrect request body json format
40053	Amount is missing.
40054	User's identifier is too long.
40055	User's IP address is invalid.
40056	Phone number is too long.
40057	Locale is invalid ISO 639-1 format.
40058	Display name is too long.
40059	User's email is invalid format.
40060	Phone number is invalid format.
40061	User object is invalid format.
40062	The value passed in the User.identifier property does not match the User.id value.
40063	Order id is missing
40101	Signature is missing.
40301	Signature is invalid.
40304	Credit card token has expired.
40305	Credit card token is already used.
40350	The IP used is not allowed for this project.
40401	Project is missing.
40402	Credit card token is invalid.
40403	Transaction does not exist.
40405	Invalid transaction state.
40406	User is missing.
40407	Transaction not confirmed.
40408	Data not valid.
40409	User not found.
40410	Project is not activated.
40411	Currency is missing.
40412	Acs return url is missing.
40413	Unsupported currency.
40414	Transaction failed. Associated entity is deactivated.
40415	Transaction failed. Associated entity is deactivated.
40416	Input data validation failed.
40417	Customer not found.
40418	Customer first name is empty.
40419	Customer last name is empty.
40420	BlackList base.
50000	Internal error.


    Error response example:

    {
        "error": {
            "code": 40001,
            "message": "Project's public key is missing."
        }
    }

Transaction status

Value	Description
created	Transaction just created, there is no payment
hold	Money are held
paid	Transaction has been paid
canceled	Payment has been canceled
refunded	Payment has been refunded
processing	Processing the payment by gateway
authenticating	Transaction is in authenticating state
waiting	Waiting for the user's action (for example, after redirect for a payment page)
failed	Payment has been failed
allowed	Action is allowed (for example, result of validation of possible payout)
forbidden	Action is forbidden (for example, result of validation of possible payout)

Payout status

Value	Description
paid	Payout has been processed
waiting	Waiting for the user's action (for example, after redirect for a payment page)
failed	Payout has been failed

Methods

For view available API methods please visit the API Reference.