L'API Payments permet d’intégrer facilement une solution de paiement sécurisée par virement simplifié (instantané ou classique) directement dans vos applications métiers.
Informations utiles :
Notre API est accessible depuis les URLs suivantes :
- api_url : https://pay.oxlin.io/v1/
- auth_url : https://pay.oxlin.io/token
Retrouvez la documentation de référence API via ce lien.
Initier et récupérer l’état d’un paiement :
Quatre étapes suffisent pour créer et surveiller un ordre de virement :
Etape 1, S’authentifier sur l’API (demande de token) :
L’API Linxo Connect est privée : vous devez avoir les autorisations nécessaires afin d’accéder à ses ressources. Pour cela vous devez fournir un token dans chaque appel API. Ce token est valable 1 heure. Obtenez un “access_token” via une requête POST /token.
Vous devez utiliser les identifiants API (client_id et client_secret) qui vous ont été fournis spécifiquement pour votre environnement dédié.
Base Url : POST https://pay.oxlin.io/v1/token
Exemple requête:
curl --request POST --location 'https://pay.oxlin.io/token' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--header 'Authorization: Basic xxxxx' \
--data-urlencode 'grant_type=client_credentials'
Exemple réponse :
{
"access_token": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
"expires_in": 8640,
"refresh_expires_in": 0,
"token_type": "Bearer",
"not-before-policy": 0,
"scope": "profile email"
}
Retrouvez la documentation de référence API sur le POST /token via ce lien.
Etape 2, Création de l’ordre de virement
Créez un ordre de virement via une requête POST /orders, en réponse vous obtiendrez l’identifiant “id” de votre ordre de virement et le lien de paiement “auth_url”. L’URL “auth_url” redirige sur le parcours client, vous devez la fournir à votre payeur.
Base Url : POST https://pay.oxlin.io/v1/orders
Exemple requête :
curl --request POST --location 'https://pay.oxlin.io/v1/orders' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer xxxxx \
--data-raw '{
"user_reference": "my user ref",
"instant_payment": "USER_CHOICE",
"redirect_url": "https://www.example.com/",
"amount": "10",
"currency": "EUR",
"email": "user@example.com",
"beneficiary":
{
"schema": "SEPA",
"iban": "FR8530003000307599775722N09",
"name": "firstname lastname"
},
"label": "transaction label"
}'
Exemple réponse :
{
"id": "d5ffac9c-57a4-468e-901a-eddf23d81db3",
"instant_payment": "USER_CHOICE",
"email": "user@example.com",
"order_status": "NEW",
"type": "PAYMENT",
"creation_date": "2024-07-22T14:12:20.083939817Z",
"auth_url": "https://pay.oxlin.io/v1/authorize/d5ffac9c-57a4-468e-901a-eddf23d81db3?client_id=xxxxx",
"redirect_url": "https://www.example.com/",
"instructions": [
{
"id": "ea46af04-50a4-4762-9e07-ce4d7ba1b6c4",
"amount": "10",
"currency": "EUR",
"beneficiary": {
"schema": "SEPA",
"iban": "FR8530003000307599775722N09",
"name": "firstname lastname",
"bic": "BICXBANKXX",
"country": "FR"
},
"label": "transaction label",
"end_to_end_id": "5b46d936e5704a4fbd4c11826083f8c5"
}
],
"payer_time_zone": "Europe/Paris",
"refundable_amount": 0
}
Retrouvez la documentation de référence API sur le POST /orders via ce lien.
Etape 3, Personnalisation du widget
Cette étape permet de personnaliser l’aspect visuel du widget Payments.
La personnalisation peut être réalisée une seule fois et consiste en la modification des paramètres de l’URL. Par la suite, ces paramètres d’URLs peuvent être utilisés sur toutes les URLs de virement.
Voici un exemple de personnalisation du widget :
Pour personnaliser le widget, nous vous conseillons d’utiliser notre outil graphique “url-builder” disponible depuis le quickstart.
Retrouvez comment personnaliser le widget depuis l’article : Personnaliser le widget Payments.
Retrouvez la documentation de référence API sur le GET /authorize via ce lien.
Etape 4, Récupération du statut de l’ordre de virement
A tout moment, consultez en temps réel les statuts de l’ordre et du paiement via un GET /running/orders.
Astuce : Inscrivez-vous à notre webhook pour être notifié en temps réel des changements sur les ordres de virement. Retrouver comment ajouter un webhook depuis l’article : Le Webhook Payments.
Base Url : GET https://pay.oxlin.io/v1/running/orders/{{order_id}}
Exemple requête:
curl --request GET --location 'https://pay.oxlin.io/v1/running/orders/{{order_id}}' \
--header 'Authorization: Bearer xxxxx'
Exemple réponse :
{
"id": "d5ffac9c-57a4-468e-901a-eddf23d81db3",
"instant_payment": "USER_CHOICE",
"email": "user@example.com",
"order_status": "NEW",
"type": "PAYMENT",
"creation_date": "2024-07-22T14:12:20.083939817Z",
"auth_url": "https://pay.oxlin.io/v1/authorize/d5ffac9c-57a4-468e-901a-eddf23d81db3?client_id=xxxxx",
"redirect_url": "https://www.example.com/",
"instructions": [
{
"id": "ea46af04-50a4-4762-9e07-ce4d7ba1b6c4",
"amount": "10",
"currency": "EUR",
"beneficiary": {
"schema": "SEPA",
"iban": "FR8530003000307599775722N09",
"name": "firstname lastname",
"bic": "BICXBANKXX",
"country": "FR"
},
"label": "transaction label",
"end_to_end_id": "5b46d936e5704a4fbd4c11826083f8c5"
}
],
"payer_time_zone": "Europe/Paris",
"refundable_amount": 0
}
Les statuts de l’ordre et du paiement sont détaillés dans l’article : Les statuts Payments.
Retrouvez la documentation de référence API sur le GET /running/orders via ce lien.
Ces informations ont-elles répondu à votre question ?
Si vous rencontrez des difficultés, n'hésitez pas à contacter notre équipe Support via ce lien