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, signature is mandatory to use this endpoint (Authentication)

Endpoint

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

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

Name	Type	Details
data	object	See Signature parameters
purchase_link_settings	object	See Signature parameters

Parameters

Object parameters

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

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

signature = jwt.encode({
        "data": {
            "merchantUid": "merchantUid"
            "title": "title",
            "reference": "reference",
            "amountCents": 2000,
            "email": "[email protected]",
            "language": "fr_FR",
            ...
        },
        "purchase_link_settings": {
            "email": "[email protected]",
            "send_email": True,
        }
    },
    "<your-secret>",
    algorithm="HS256",
)
print(f"/api/purchase_link/?signature={signature}")

/api/purchase_link/?signature=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJkYXRhIjp7InRpdGxlIjoidGVzdF9hcGlfcHVyY2hhc2UiLCJyZWZlcmVuY2UiOiJ0ZXN0X3JlZmVyZW5jZSIsImFtb3VudENlbnRzIjoyMDAwLCJlbWFpbCI6ImVtYWlsQGRvbWFpbi5jb20ifSwicHVyY2hhc2VfbGlua19zZXR0aW5ncyI6eyJlbWFpbCI6ImVtYWlsQGRvbWFpbi5jb20iLCJsYW5ndWFnZSI6ImZyX0ZSIiwic2VuZF9lbWFpbCI6dHJ1ZX19.Vs-AdDrfTYa8muNbFnGexi1stCGzDb8P19IV4P0eeFg

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, signature is mandatory to use this endpoint (Authentication)

Endpoint

GET /api/purchase_status/?signature=<signature>

Parameters

Parameters must be sent within the signature.
All the fields should be in a data object.
The data field with the following structure:

Name	Type	Details
merchantUid	string	Your merchant unique identifier
purchaseUid	string	Purchase unique identifier
reference	string	Purchase unique reference

To identify the purchase, use either the Pledg identifier purchaseUid or the reference that you provided to us when creating the purchase.

Request example

signature = jwt.encode({
    "data": {
        "purchaseUid": "pur_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx",
        "merchantUid": "mer_xxxxxxxx-xxx-xxxx-xxxx-xxxxxxxxxxxx"}
    },
    "<your-secret>",
    algorithm="HS256",
)
print(f"/api/purchase_status/?signature={signature}")

/api/purchase_status/?signature=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJwdXJjaGFzZVVpZCI6InB1cl94eHh4eHh4eC14eHgteHh4eC14eHh4LXh4eHh4eHh4eHh4eCIsIm1lcmNoYW50VWlkIjoibWVyX3h4eHh4eHh4LXh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4In0.-2Y64T0PrVIOD9P6FCwB5l9Ql-Nx3sGXxvta-lh0xXA

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.