Purchase management

You can create a purchase link, check a purchase status or trigger a capture via API.

Purchase creation

Will create a purchase with specified informations, a link for this purchase will be provided.

Authentication

For security reasons, an access token is mandatory to use this endpoint (Authentication).

Endpoint

POST /api/merchants/<merchant_uid>/purchase_link

All the parameters must be sent within the body with the following structure:

Name	Type	Details
data	object	See Parameters
purchase_link_settings	object	See Parameters

Parameters

Object parameters

The data is used to create the purchase, the object contains the same parameters as for a new purchase.

The purchase_link_settings object parameter should be like this:

Name	Type	Details
send_email	boolean	Wether the link should be sent by email.
email	string	The email where the link should be sent.
send_sms	boolean	Wether the link should be sent by sms.
phone_number	string	The phone number where the link should be sent.

With email

"purchase_link_settings": {
    "email": "[email protected]",
    "send_email": true,
}

With sms

"purchase_link_settings": {
    "phone_number": "+33600000000",
    "send_sms": true
}

With email and sms

"purchase_link_settings": {
    "email": "[email protected]",
    "send_email": true,
    "phone_number": "+33600000000",
    "send_sms": true
}

Request example

        "data": {
            "merchantUid": "merchantUid"
            "title": "title",
            "reference": "reference",
            "amountCents": 2000,
            "email": "[email protected]",
            "language": "fr_FR",
            ...
        },
        "purchase_link_settings": {
            "email": "[email protected]",
            "send_email": True,
        }

Responses

Name	Type	Details
purchase_uid	string	The purchase unique identifier.
url	string	The url that allows the payment and the validation of the purchase.
email_has_been_sent	boolean	Wether the link was successfully sent by email.
sms_has_been_sent	boolean	Wether the link was successfully sent by sms.

Response examples

With email, Status 200

{
    "url": "s.sofin.co/s/ndm3Ypco",
    "purchase_uid": "pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email_has_been_sent": true
}

Sent by email and sms, Status 200

{
    "url": "s.sofin.co/s/ndm3Ypco",
    "purchase_uid": "pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx",
    "email_has_been_sent": true,
    "sms_has_been_sent": true
}

Purchase status

The status of any existing purchase can be checked using a http call.

Authentication

For security reasons, an access token is mandatory to use this endpoint (Authentication).

Endpoint

GET /api/purchases/<purchase_uid>/status

Response

Name	Type	Details
purchase_uid	string	The purchase unique identifier.
status	string	The current purchase status (among OK, PENDING, FAILED).
outstanding_amount_cents	integer	Remaining amount owed by the buyer. Having an outstanding balance doesn't mean it's past due.
past_due_num_of_days	integer	The number of days past due (past due refers to a bill not paid by its due date)

Response example

Status 200

{
    "purchase_uid": "pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx",
    "status": "OK",
    "outstanding_amount_cents": 10500,
    "past_due_num_of_days": 0,
}

Trigger capture

For deferred payment solutions, depending on your merchant configuration, due date can be advanced.

Authentication

For security reasons, signature is mandatory to use this endpoint (Authentication)

Endpoint

POST /api/trigger_capture/?signature=<signature>

Parameters

The signature parameter is the same as the example above.

Response

• 200 if succeed.
• 400 if the signature is invalid
• 400 if merchantUid or (purchaseUid and reference) are missing.
• 400 if the purchase is not in a valid state.
• 404 if merchantUid or purchaseUid or reference are not found.

Abort a purchase

Please note that a purchase can only be canceled if it is still in its early stages.

Authentication

For security reasons, an access token is mandatory to use this endpoint (Authentication)

Endpoint

POST /api/purchases/<purchase_uid>/abort

Response statuses

The endpoint will return a 200 http status code in case of success.

You will receive a 4xx http status code along with a raw text explanation in case of error.

Code	Description
200	the purchase is aborted
401	Invalid credentials
404	Invalid purchase UID
409	This purchase is non-abortable (purchase_non_abortable) or already aborted (purchase_already_aborted)

Response examples

Status 200

{
    "purchase_uid": "pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx",
    "state":  "ABORTED"
}

Status 409

{
    "error": {
        "app_error": "purchase_already_aborted",
        "debug": "The purchase pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx has already been aborted",
        "info": "L'achat est déjà annulé"
    }
}