Integration of the Pledg payment solution

# 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.

← Payment schedule simulation →