{"activeVersionTag":"latest","latestAvailableVersionTag":"latest","collection":{"info":{"_postman_id":"22a6a5b1-a0f6-458c-be1d-b1eee0a7a570","name":"Banq Open API Documentation","description":"![logo](https://banqopenapistorage.blob.core.windows.net/doc-images/icons/logo.png)\n\n# Intro\nBanq's Open API helps to integrate with Banq functionality related to payment creation and payments/transaction tracking. Using Open API one can create requests to get paid, browse banqs within the system, retrieve payment transactions, and setup webhooks to get notified about changes.\n\n# Guides\n\nPlease take a look at the [guides](https://developers.banq.com/docs) in our [developer center](https://developers.banq.com) for integration information.\n\n# Authentication\nAuthentication is performed via the [Auth0](https://auth0.com/) platform based on API `client_id` and `username/password`. Integrators are represented as an M2M Application that that interacts with the **Banq API** on  behalf of the Banq user. [Client credentials flow](https://auth0.com/docs/flows/client-credentials-flow) should be used  to obtain the access token and use it in the `Authorization` header with the `Bearer ` prefix to access **Banq API**.  \n\nYou need to POST to Auth0 endpoint `/oauth/token` following values (see example in __Authentication__ folder:\n+ `client_id` identifier of the M2M Application\n+ `username` username for the M2M Application\n+ `password` password for the M2M Application\n+ `audience`: `https://banq.com/open/api/`\n+ `grant_type`: `password`   \n\nAll Open API operations are performed on this user's behalf.\n\n# Error Codes\n`200` - the request was performed successfully and the relevant response is returned.  \n`201` - the entity was created successfully and is returned in the response. This entity is accessible at the link sent in the `Location` response header.  \n`400` - the request was malformed or some business rules were not satisfied. Returns error message.  \n`401` - there were problems with the access token or it is missing.  \n`403` - the operation is forbidden for the current user.  \n`404` - the entity was not found in the system.  \n`422` - due to validation errors or external reasons, the request cannot be processed.\n\n# Transaction fail reasons \n- `None` - default transaction fail reason.\n- `ProcessingFailed` - processing failed.\n- `LimitsExceeded` - limits exceeded.\n- `FingerprintBlacklisted` - finger print blacklisted.\n- `BanqError` - the banq error.\n- `PrimeTrustError` - the prime trust error.\n- `InsufficientBalance` - exception is caused by insufficient balance.\n- `CustodialAccountContactIsNotApproved` - the custodial account contact is not approved.\n- `ExternalAccountIsDeactivated` - the external account is deactivated.\n- `PlaidRequiresReAuthentication` - the plaid requires re authentication.\n- `AccountIsFrozen` - the account is frozen.\n- `Reversed` - transaction is reversed.\n- `Cancelled` - transaction is cancelled.\n\n# Pagination\nSome endpoints return data in pages. They accept the following query parameters that control pagination:\n- `page` - one-based number of the page;\n- `pageSize` - the number of items that will be returned.   \n\nThe response contains `meta` property that holds an object with the following data:\n- `resourceCount` - total number of filtered items in the system;\n- `pageCount` - total number of pages calculated using query parameters `page` and `pageSize`.\nThe response also contains property `data` with a collection of entities.\n\n# Idempotent headers\nThe API allows performing idempotent POST requests. To enable this feature one needs to add `X-Idempotent-Id` header with a unique identifier (GUID). All subsequent requests with this header will return the same response as the first one.\n\n# Webhooks\nWhenever changes to payment or transaction object are made, a webhook is sent to the URL set in POST/PUT `api/v1/account-spaces/{accountSpaceId}/webhook-config`.  \nThe webhook structure looks like this:  \n\n```json\n{\n  \"accountSpaceId\": 1, // identifier of the account space related to the operation that triggered the webhook\n  \"action\": \"Created\", // a string representation of what happened to the resource\n  \"id\": \"c88d829b-c2c1-4c78-9b07-e7667ee399ff\", // unique identifier of this webhook\n  \"resourceId\": \"9bf48226-79c3-43d2-9be5-264bfef4660d\", // identifier of the entity that has changed\n  \"resourceType\": \"Transaction\", // the type of the entity\n  \"createdAtUtc\": \"2021-01-11T12:12:12.5431424+00:00\" // time of webhook creation\n}\n```  \n\nFor now, we send webhooks for `resourceType`:  \n\n| `\"resourceType\"` | `\"action\"` |\n| ----------- | ----------- |\n| `\"Payment\"` | `\"Created\"`, `\"Completed\"`, `\"Accepted\"`, `\"Declined\"`, `\"OnHold\"`, `\"Canceled\"`, `\"Expired\"`, `\"Resumed\"`, `\"OccurrenceCanceled\"` |\n| `\"Transaction\"` | `\"Created\"`, `\"Failed\"`, `\"Updated\"` |\n\n# Payments\nOur notification system sends webhooks whenever there are some changes in payments or transactions. For example, let us consider a typical Open API flow:\n+ Integrator creates a one time request to get paid via `api/v1/payments/get-paid-direct`: a __payment__ entity is created in Banq system; webhook with `\"resourceType\": \"Payment\"` and `\"action\": \"Created\"` is scheduled.\n+ A Banq user accepts this request via mobile app:\n    + a __payment__ status changes to `\"Accepted\"`; webhook with `\"resourceType\": \"Payment\"` and `\"action\": \"Accepted\"` is scheduled.\n    + a __transaction__ is created:\n        + if it is successfull, a webhook with `\"resourceType\": \"Transaction\"` and `\"action\": \"Created\"` is scheduled.\n        + if it fails, a webhook with `\"resourceType\": \"Transaction\"` and `\"action\": \"Failed\"` is scheduled.\n\t+ a __payment__ status changes to `\"Completed\"`; a webhook with `\"resourceType\": \"Payment\"` and `\"action\": \"Completed\"` is scheduled.\n\n# Webhook message authentication\nTo enable integrity and authenticity verification of a HTTP webhook message, we append a `X-Banq-Webhook-Hmac` header with base 64 encoded HMAC value. This HMAC value is calculated over the webhook request body using `SharedSecret`. `SharedSecret` is set in the request body to POST `api/v1/account-spaces/{accountSpaceId}/webhook-config` endpoint. HMAC value is calculated with SHA256 hashing algorithm.","schema":"https://schema.getpostman.com/json/collection/v2.0.0/collection.json","isPublicCollection":false,"owner":"11378575","collectionId":"22a6a5b1-a0f6-458c-be1d-b1eee0a7a570","publishedId":"TVzSjHF8","public":true,"publicUrl":"https://docs.banq.com","privateUrl":"https://go.postman.co/documentation/11378575-22a6a5b1-a0f6-458c-be1d-b1eee0a7a570","customColor":{"top-bar":"303030","right-sidebar":"303030","highlight":"7622A9"},"documentationLayout":"classic-double-column","customisation":null,"version":"8.10.0","publishDate":"2021-03-25T18:42:35.000Z","activeVersionTag":"latest","documentationTheme":"light","metaTags":{},"logos":{}},"statusCode":200},"environments":[],"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/0facc1bc3e9865295728f3e853b52c535378a6ebc864bca08d54858bc8fbb864","favicon":"https://banq.com/favicon.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"}],"canonicalUrl":"https://docs.banq.com/view/metadata/TVzSjHF8"}