{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"8310aa3a-cc8b-4c23-bb9d-d59ef11cc85b","name":"Swile payments integration","description":"This documentation explains how you can use Swile APIs and connect a Swile account to your application in order to place payments.\n\n**Note**: You'll need to use 3 servers to integrate Swile payments:\n\n- one for the authentication :\n    \n    ``` json\n    directory.swile.co \n    \n    ```\n    \n- one for the banking operations :\n    \n    ``` json\n    banking-api.swile.co\n    \n    ```\n    \n- one for the vendor merchant operations :\n    \n    ``` json\n    affiliates-api.swile.co\n    \n    ```\n    \n\n## How to ?\n\n[Here you'll find a flowchart represents](https://whimsical.com/Dffb5KPJNhL3j5B6GWTKi8) the main exchanges between our differents APIs and your integraton.\n\nFirst step is to get an access token, using an OAuth authentication flow, from the user to be able to request the Banking API.\n\n## 1- Get an authorization code for the user\n\nLet the user visit the `oauth/authorize` endpoint (this flow should NOT be done inside an iFrame but using full-page navigation). The user will be asked to sign in with their Swile account credentials, and will then have to accept sharing their information (wallet info, payments) to your application.\n\nOnce the user grants the permissions to your application, he be redirected to the given `redirect_uri` with the authorization code in the query parameter `code`.\n\n## 2- Exchange the received `code` for an `access_token`\n\nUse `POST /oauth/token` to authenticate the user to your app and exchange the receiving `code` with an `access_token` and a `refresh_token`.\n\nThe `access_token` is a JWT (JSON Web Token) containing the `banking_account_uuid` (named `account_uuid` in the next section) of the user.\n\n## 3- Place a payment with the Banking API\n\n**Check the payment integrity**\n\nOnce you get the user's `access_token` you'll be able to place payments.  \nBefore actually placing a payment, you can check if the payment would be valid and accepted (with `POST /api/v1/accounts/:account_uuid/payments/check`) depending on:\n\n- the user daily available balance\n- the merchant eligibility to Meal Vouchers\n- the date (some users are only allowed to use meal vouchers during the week for instance)\n    \n\\=> This can allow you to decide if you want to display the _\"Pay with Swile\"_ button or not.\n\n**Place the payment**\n\nUse `POST /api/v1/accounts/:account_uuid/payments` after the check to proceed with the payment. If successful, you'll get a 201 with the `uuid` of the payment (named `payment_uuid` in the next section). Make sure to store this value, as there is no endpoint available that will return you the list of the user's payments.\n\n**Note**: A best practice is to set `only_authorize: true` to only request an authorization (or pre-authorization) which will freeze the amount until explicitely captured by the `capture` endpoint (see below). Authorizations are only valid for a week and expire automatically afterwards. If you want to release an authorization earlier, you can use the `/api/v1/payments/:payment_uuid/refund` endpoint.\n\n**Capture a payment**\n\nIf `/api/v1/accounts/:account_uuid/payments` was called with `only_authorize: true`, you'll need to use `PUT /api/v1/payments/:payment_uuid/capture` to complete the payment by capturing the total authorized amount (or less).\n\n**Refund a payment**\n\nUse `PUT /api/v1/payments/:payment_uuid/refund` to refund totally or partially the user if needed\n\n## Pay more than 19€ in restaurant\n\n> As you may have heard, a new decree has been ratified since june 12th 2020 to support the restaurant industry by relaxing the rules surrounding the expenditure of meal vouchers. You'll find all details in [this documentation](https://www.notion.so/swile/Pay-more-than-19-in-restaurants-with-the-Swile-API-07f3df1abd1542c6b628f70e36b34a03)","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"9483050","collectionId":"8310aa3a-cc8b-4c23-bb9d-d59ef11cc85b","publishedId":"Szf9WTJp","public":true,"publicUrl":"https://docs.swile.co","privateUrl":"https://go.postman.co/documentation/9483050-8310aa3a-cc8b-4c23-bb9d-d59ef11cc85b","customColor":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"633FD3"},"documentationLayout":"classic-double-column","customisation":{"metaTags":[{"name":"description","value":""},{"name":"title","value":""}],"appearance":{"default":"light","themes":[{"name":"dark","logo":null,"colors":{"top-bar":"212121","right-sidebar":"303030","highlight":"FF6C37"}},{"name":"light","logo":null,"colors":{"top-bar":"FFFFFF","right-sidebar":"303030","highlight":"633FD3"}}]}},"version":"8.10.0","publishDate":"2023-04-25T12:40:51.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{"title":"","description":""},"logos":{"logoLight":null,"logoDark":null}},"statusCode":200},"environments":[{"name":"production","id":"3519bde8-33a2-4621-b68e-47fd00fd580e","owner":"9483050","values":[{"key":"customer-api","value":"https://customer-api.swile.co","enabled":true},{"key":"banking-api","value":"https://banking-api.swile.co","enabled":true},{"key":"affiliate-api","value":"https://affiliate-api.swile.co","enabled":true},{"key":"loop-api","value":"https://loop-api.swile.co","enabled":true},{"key":"affiliates-api","value":"https://affiliates-api.swile.co","enabled":true},{"key":"directory-api","value":"https://directory.swile.co","enabled":true},{"key":"directory","value":"directory.swile.co","enabled":true},{"key":"bearer_token","value":"","enabled":true},{"key":"application_token","value":"","enabled":true},{"key":"vendor_id","value":"","enabled":true},{"key":"wallet-id","value":"","enabled":true,"type":"default"},{"key":"benefits-mobility-fr","value":"https://benefits-mobility-fr-api.swile.co","enabled":true,"type":"default"},{"key":"organisation-id","value":"","enabled":true,"type":"default"},{"key":"user_token","value":"","enabled":true,"type":"any"}],"published":true}],"user":{"authenticated":false,"permissions":{"publish":false}},"run":{"button":{"js":"https://run.pstmn.io/button.js","css":"https://run.pstmn.io/button.css"}},"web":"https://www.getpostman.com/","team":{"logo":"https://res.cloudinary.com/postman/image/upload/t_team_logo_pubdoc/v1/team/97c1a20e483437eb3da6e4dd38ba3cfa825e51aef786c0f8249bd33e270c4095","favicon":"https://res.cloudinary.com/postman/image/upload/v1651243924/team/kwa6kdqv29jxflpia254.ico"},"isEnvFetchError":false,"languages":"[{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"HttpClient\"},{\"key\":\"csharp\",\"label\":\"C#\",\"variant\":\"RestSharp\"},{\"key\":\"curl\",\"label\":\"cURL\",\"variant\":\"cURL\"},{\"key\":\"dart\",\"label\":\"Dart\",\"variant\":\"http\"},{\"key\":\"go\",\"label\":\"Go\",\"variant\":\"Native\"},{\"key\":\"http\",\"label\":\"HTTP\",\"variant\":\"HTTP\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"OkHttp\"},{\"key\":\"java\",\"label\":\"Java\",\"variant\":\"Unirest\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"Fetch\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"jQuery\"},{\"key\":\"javascript\",\"label\":\"JavaScript\",\"variant\":\"XHR\"},{\"key\":\"c\",\"label\":\"C\",\"variant\":\"libcurl\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Axios\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Native\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Request\"},{\"key\":\"nodejs\",\"label\":\"NodeJs\",\"variant\":\"Unirest\"},{\"key\":\"objective-c\",\"label\":\"Objective-C\",\"variant\":\"NSURLSession\"},{\"key\":\"ocaml\",\"label\":\"OCaml\",\"variant\":\"Cohttp\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"cURL\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"Guzzle\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"HTTP_Request2\"},{\"key\":\"php\",\"label\":\"PHP\",\"variant\":\"pecl_http\"},{\"key\":\"powershell\",\"label\":\"PowerShell\",\"variant\":\"RestMethod\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"http.client\"},{\"key\":\"python\",\"label\":\"Python\",\"variant\":\"Requests\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"httr\"},{\"key\":\"r\",\"label\":\"R\",\"variant\":\"RCurl\"},{\"key\":\"ruby\",\"label\":\"Ruby\",\"variant\":\"Net::HTTP\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"Httpie\"},{\"key\":\"shell\",\"label\":\"Shell\",\"variant\":\"wget\"},{\"key\":\"swift\",\"label\":\"Swift\",\"variant\":\"URLSession\"}]","languageSettings":[{"key":"csharp","label":"C#","variant":"HttpClient"},{"key":"csharp","label":"C#","variant":"RestSharp"},{"key":"curl","label":"cURL","variant":"cURL"},{"key":"dart","label":"Dart","variant":"http"},{"key":"go","label":"Go","variant":"Native"},{"key":"http","label":"HTTP","variant":"HTTP"},{"key":"java","label":"Java","variant":"OkHttp"},{"key":"java","label":"Java","variant":"Unirest"},{"key":"javascript","label":"JavaScript","variant":"Fetch"},{"key":"javascript","label":"JavaScript","variant":"jQuery"},{"key":"javascript","label":"JavaScript","variant":"XHR"},{"key":"c","label":"C","variant":"libcurl"},{"key":"nodejs","label":"NodeJs","variant":"Axios"},{"key":"nodejs","label":"NodeJs","variant":"Native"},{"key":"nodejs","label":"NodeJs","variant":"Request"},{"key":"nodejs","label":"NodeJs","variant":"Unirest"},{"key":"objective-c","label":"Objective-C","variant":"NSURLSession"},{"key":"ocaml","label":"OCaml","variant":"Cohttp"},{"key":"php","label":"PHP","variant":"cURL"},{"key":"php","label":"PHP","variant":"Guzzle"},{"key":"php","label":"PHP","variant":"HTTP_Request2"},{"key":"php","label":"PHP","variant":"pecl_http"},{"key":"powershell","label":"PowerShell","variant":"RestMethod"},{"key":"python","label":"Python","variant":"http.client"},{"key":"python","label":"Python","variant":"Requests"},{"key":"r","label":"R","variant":"httr"},{"key":"r","label":"R","variant":"RCurl"},{"key":"ruby","label":"Ruby","variant":"Net::HTTP"},{"key":"shell","label":"Shell","variant":"Httpie"},{"key":"shell","label":"Shell","variant":"wget"},{"key":"swift","label":"Swift","variant":"URLSession"}],"languageOptions":[{"label":"C# - HttpClient","value":"csharp - HttpClient - C#"},{"label":"C# - RestSharp","value":"csharp - RestSharp - C#"},{"label":"cURL - cURL","value":"curl - cURL - cURL"},{"label":"Dart - http","value":"dart - http - Dart"},{"label":"Go - Native","value":"go - Native - Go"},{"label":"HTTP - HTTP","value":"http - HTTP - HTTP"},{"label":"Java - OkHttp","value":"java - OkHttp - Java"},{"label":"Java - Unirest","value":"java - Unirest - Java"},{"label":"JavaScript - Fetch","value":"javascript - Fetch - JavaScript"},{"label":"JavaScript - jQuery","value":"javascript - jQuery - JavaScript"},{"label":"JavaScript - XHR","value":"javascript - XHR - JavaScript"},{"label":"C - libcurl","value":"c - libcurl - C"},{"label":"NodeJs - Axios","value":"nodejs - Axios - NodeJs"},{"label":"NodeJs - Native","value":"nodejs - Native - NodeJs"},{"label":"NodeJs - Request","value":"nodejs - Request - NodeJs"},{"label":"NodeJs - Unirest","value":"nodejs - Unirest - NodeJs"},{"label":"Objective-C - NSURLSession","value":"objective-c - NSURLSession - Objective-C"},{"label":"OCaml - Cohttp","value":"ocaml - Cohttp - OCaml"},{"label":"PHP - cURL","value":"php - cURL - PHP"},{"label":"PHP - Guzzle","value":"php - Guzzle - PHP"},{"label":"PHP - HTTP_Request2","value":"php - HTTP_Request2 - PHP"},{"label":"PHP - pecl_http","value":"php - pecl_http - PHP"},{"label":"PowerShell - RestMethod","value":"powershell - RestMethod - PowerShell"},{"label":"Python - http.client","value":"python - http.client - Python"},{"label":"Python - Requests","value":"python - Requests - Python"},{"label":"R - httr","value":"r - httr - R"},{"label":"R - RCurl","value":"r - RCurl - R"},{"label":"Ruby - Net::HTTP","value":"ruby - Net::HTTP - Ruby"},{"label":"Shell - Httpie","value":"shell - Httpie - Shell"},{"label":"Shell - wget","value":"shell - wget - Shell"},{"label":"Swift - URLSession","value":"swift - URLSession - Swift"}],"layoutOptions":[{"value":"classic-single-column","label":"Single Column"},{"value":"classic-double-column","label":"Double Column"}],"versionOptions":[],"environmentOptions":[{"value":"0","label":"No Environment"},{"label":"production","value":"9483050-3519bde8-33a2-4621-b68e-47fd00fd580e"}],"canonicalUrl":"https://docs.swile.co/view/metadata/Szf9WTJp"}