{"__v":15,"_id":"5452be95b7fa011600a75c4d","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[{"language":"json","code":"{}","name":"Success"},{"language":"json","code":"{}","name":"Failure"}]},"settings":"","try":true,"url":""},"body":"[Payout](http://www.payout.com) makes it easy to disburse funds to your customers. Whether you need to disburse an insurance claim, a paycheck or a loan, [Payout](http://www.payout.com) can ensure your customers receive their funds on time.\n\n[Payout](http://www.payout.com) not only support traditional ACH disbursements to bank accounts, but also instant disbursements to debit and credit cards any day of the week.  This allows you to give your customers their money when they actually need it and not in 2-3 business days.\n\nCheck out our API docs below, and [sign up](https://dashboard.payout.com/users/sign_up) for sandbox access when your ready.","category":"5452be95b7fa011600a75c4c","createdAt":"2014-08-25T20:57:43.852Z","excerpt":"","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":0,"project":"53fba347e406d10c30ed5f61","slug":"introduction","sync_unique":"","title":"Introduction","type":"basic","updates":[],"user":"5250b3ad5ac09b3564000005","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Introduction


[Payout](http://www.payout.com) makes it easy to disburse funds to your customers. Whether you need to disburse an insurance claim, a paycheck or a loan, [Payout](http://www.payout.com) can ensure your customers receive their funds on time. [Payout](http://www.payout.com) not only support traditional ACH disbursements to bank accounts, but also instant disbursements to debit and credit cards any day of the week. This allows you to give your customers their money when they actually need it and not in 2-3 business days. Check out our API docs below, and [sign up](https://dashboard.payout.com/users/sign_up) for sandbox access when your ready.
[Payout](http://www.payout.com) makes it easy to disburse funds to your customers. Whether you need to disburse an insurance claim, a paycheck or a loan, [Payout](http://www.payout.com) can ensure your customers receive their funds on time. [Payout](http://www.payout.com) not only support traditional ACH disbursements to bank accounts, but also instant disbursements to debit and credit cards any day of the week. This allows you to give your customers their money when they actually need it and not in 2-3 business days. Check out our API docs below, and [sign up](https://dashboard.payout.com/users/sign_up) for sandbox access when your ready.
{"__v":13,"_id":"5452be95b7fa011600a75c4e","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[{"language":"json","code":"{}","name":"Success"},{"language":"json","code":"{}","name":"Failure"}]},"settings":"","try":true,"url":""},"body":"Authentication with Payout requires an API token and an API secret.  They'll look something like this:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"API Token\",\n    \"h-1\": \"API Secret\",\n    \"0-0\": \"QS5UTsIp2Jw\",\n    \"0-1\": \"i2I5Bq3VbucrFBT8lACQwb\"\n  },\n  \"cols\": 2,\n  \"rows\": 1\n}\n[/block]\nThese are passed in each API request via HTTP basic authentication as the username and password, respectively.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl https://QS5UTsIp2Jw:i2I5Bq3VbucrFBT8lACQwb@sandbox.payout.com/v1/balance\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]\nYou can obtain your API token and secret from the [dashboard](https://dashboard.payout.com/api).  You can also rotate either credential from there as well.\n\n***IMPORTANT:*** Never expose your API secret on your client. It grants access to *all* API endpoints.  Make sure to only send the API token when authenticating with tokenization endpoints.\n\nFor example:\n[block:code]\n{\n  \"codes\": [\n    {\n      \"code\": \"curl -X POST https://QS5UTsIp2Jw:@sandbox.payout.com/v1/cards -H \\\"Content-Type: application/json\\\" -d '{\\\"name\\\": \\\"John Smith\\\",\\\"card_number\\\":\\\"4111111111111111\\\",\\\"exp_month\\\":\\\"10\\\",\\\"exp_year\\\":\\\"16\\\"}'\",\n      \"language\": \"shell\"\n    }\n  ]\n}\n[/block]","category":"5452be95b7fa011600a75c4c","createdAt":"2014-08-25T23:08:09.890Z","excerpt":"","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":1,"project":"53fba347e406d10c30ed5f61","slug":"authentication-details","sync_unique":"","title":"Authentication Details","type":"basic","updates":[],"user":"5250b3ad5ac09b3564000005","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Authentication Details


Authentication with Payout requires an API token and an API secret. They'll look something like this: [block:parameters] { "data": { "h-0": "API Token", "h-1": "API Secret", "0-0": "QS5UTsIp2Jw", "0-1": "i2I5Bq3VbucrFBT8lACQwb" }, "cols": 2, "rows": 1 } [/block] These are passed in each API request via HTTP basic authentication as the username and password, respectively. For example: [block:code] { "codes": [ { "code": "curl https://QS5UTsIp2Jw:i2I5Bq3VbucrFBT8lACQwb@sandbox.payout.com/v1/balance", "language": "shell" } ] } [/block] You can obtain your API token and secret from the [dashboard](https://dashboard.payout.com/api). You can also rotate either credential from there as well. ***IMPORTANT:*** Never expose your API secret on your client. It grants access to *all* API endpoints. Make sure to only send the API token when authenticating with tokenization endpoints. For example: [block:code] { "codes": [ { "code": "curl -X POST https://QS5UTsIp2Jw:@sandbox.payout.com/v1/cards -H \"Content-Type: application/json\" -d '{\"name\": \"John Smith\",\"card_number\":\"4111111111111111\",\"exp_month\":\"10\",\"exp_year\":\"16\"}'", "language": "shell" } ] } [/block]
Authentication with Payout requires an API token and an API secret. They'll look something like this: [block:parameters] { "data": { "h-0": "API Token", "h-1": "API Secret", "0-0": "QS5UTsIp2Jw", "0-1": "i2I5Bq3VbucrFBT8lACQwb" }, "cols": 2, "rows": 1 } [/block] These are passed in each API request via HTTP basic authentication as the username and password, respectively. For example: [block:code] { "codes": [ { "code": "curl https://QS5UTsIp2Jw:i2I5Bq3VbucrFBT8lACQwb@sandbox.payout.com/v1/balance", "language": "shell" } ] } [/block] You can obtain your API token and secret from the [dashboard](https://dashboard.payout.com/api). You can also rotate either credential from there as well. ***IMPORTANT:*** Never expose your API secret on your client. It grants access to *all* API endpoints. Make sure to only send the API token when authenticating with tokenization endpoints. For example: [block:code] { "codes": [ { "code": "curl -X POST https://QS5UTsIp2Jw:@sandbox.payout.com/v1/cards -H \"Content-Type: application/json\" -d '{\"name\": \"John Smith\",\"card_number\":\"4111111111111111\",\"exp_month\":\"10\",\"exp_year\":\"16\"}'", "language": "shell" } ] } [/block]
{"__v":16,"_id":"5452be95b7fa011600a75c4f","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[{"language":"json","code":"{}","name":"Success"},{"language":"json","code":"{}","name":"Failure"}]},"settings":"","try":true,"url":""},"body":"The sandbox environment is intended only for testing purposes and does not support real card transactions.  You can obtain your Sandbox API credentials from the [dashboard](https://dashboard.payout.com/api).\n\n## Test Cards\nThe following card numbers can be used in the sandbox environment with any valid expiration (i.e., in the future). Any other card number will be treated as an unsupported card.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Number\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"4111111111111111\",\n    \"1-0\": \"4111111111111129\",\n    \"0-1\": \"Successful tokenization and successful credits.\",\n    \"1-1\": \"Successfully tokenizes but returns card_expired when crediting (regardless of the expiration date you specify).\\n\\nThis is useful to test when a previously tokenized card has since expired.\",\n    \"2-0\": \"4111111111111137\",\n    \"2-1\": \"Simulates successful tokenization (card will appear **ready**) but results in a **card_declined** error when crediting.\",\n    \"3-0\": \"4111111111111145\",\n    \"3-1\": \"Simulates successful tokenization (card will appear **ready**) but results in a **transaction_declined** error when crediting.\\n\\n*In the Live environment, this should be a small percentage of credits but can happen if the card is on a supported network but the specific bank is not prepared to handle the transaction type.*\",\n    \"4-0\": \"4211111111111110\",\n    \"4-1\": \"Simulates a successful asynchronous transaction. When crediting this card, it will return with a state of `scheduled`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 5\n}\n[/block]\n## Test Bank Accounts\nThe following bank account and routing numbers can be used in the sandbox environment.\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Account Number\",\n    \"h-1\": \"ACH Routing Number\",\n    \"h-2\": \"Description\",\n    \"0-1\": \"120000003\",\n    \"0-0\": \"111111111\",\n    \"0-2\": \"Accepts test ACH deposits.\"\n  },\n  \"cols\": 3,\n  \"rows\": 1\n}\n[/block]\n## Billing Address Verification\nTo test the different [billing address verification](doc:billing-address-verification) responses, use the following values.\n\n### Street Address Test Values\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Value\",\n    \"h-1\": \"Test trigger\",\n    \"0-0\": \"`yes`\",\n    \"1-0\": \"`no`\",\n    \"2-0\": \"`n/a`\",\n    \"0-1\": \"Any `line1` that does not match the conditions below.\",\n    \"1-1\": \"If the `line1` value starts with `101` followed by any other characters.\",\n    \"2-1\": \"If the `line1` value starts with `202` followed by any other characters.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n### Postal Code Test Values\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"Value\",\n    \"h-1\": \"Test trigger\",\n    \"0-0\": \"`yes`\",\n    \"1-0\": \"`no`\",\n    \"2-0\": \"`n/a`\",\n    \"0-1\": \"Any `postal_code` that does not match the conditions below.\",\n    \"1-1\": \"If `postal_code` equals `10001`.\",\n    \"2-1\": \"If `postal_code` equals `20002`.\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]","category":"5452be95b7fa011600a75c4c","createdAt":"2014-10-14T21:48:54.005Z","excerpt":"","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":2,"project":"53fba347e406d10c30ed5f61","slug":"sandbox-access","sync_unique":"","title":"Sandbox Access","type":"basic","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Sandbox Access


The sandbox environment is intended only for testing purposes and does not support real card transactions. You can obtain your Sandbox API credentials from the [dashboard](https://dashboard.payout.com/api). ## Test Cards The following card numbers can be used in the sandbox environment with any valid expiration (i.e., in the future). Any other card number will be treated as an unsupported card. [block:parameters] { "data": { "h-0": "Number", "h-1": "Description", "0-0": "4111111111111111", "1-0": "4111111111111129", "0-1": "Successful tokenization and successful credits.", "1-1": "Successfully tokenizes but returns card_expired when crediting (regardless of the expiration date you specify).\n\nThis is useful to test when a previously tokenized card has since expired.", "2-0": "4111111111111137", "2-1": "Simulates successful tokenization (card will appear **ready**) but results in a **card_declined** error when crediting.", "3-0": "4111111111111145", "3-1": "Simulates successful tokenization (card will appear **ready**) but results in a **transaction_declined** error when crediting.\n\n*In the Live environment, this should be a small percentage of credits but can happen if the card is on a supported network but the specific bank is not prepared to handle the transaction type.*", "4-0": "4211111111111110", "4-1": "Simulates a successful asynchronous transaction. When crediting this card, it will return with a state of `scheduled`." }, "cols": 2, "rows": 5 } [/block] ## Test Bank Accounts The following bank account and routing numbers can be used in the sandbox environment. [block:parameters] { "data": { "h-0": "Account Number", "h-1": "ACH Routing Number", "h-2": "Description", "0-1": "120000003", "0-0": "111111111", "0-2": "Accepts test ACH deposits." }, "cols": 3, "rows": 1 } [/block] ## Billing Address Verification To test the different [billing address verification](doc:billing-address-verification) responses, use the following values. ### Street Address Test Values [block:parameters] { "data": { "h-0": "Value", "h-1": "Test trigger", "0-0": "`yes`", "1-0": "`no`", "2-0": "`n/a`", "0-1": "Any `line1` that does not match the conditions below.", "1-1": "If the `line1` value starts with `101` followed by any other characters.", "2-1": "If the `line1` value starts with `202` followed by any other characters." }, "cols": 2, "rows": 3 } [/block] ### Postal Code Test Values [block:parameters] { "data": { "h-0": "Value", "h-1": "Test trigger", "0-0": "`yes`", "1-0": "`no`", "2-0": "`n/a`", "0-1": "Any `postal_code` that does not match the conditions below.", "1-1": "If `postal_code` equals `10001`.", "2-1": "If `postal_code` equals `20002`." }, "cols": 2, "rows": 3 } [/block]
The sandbox environment is intended only for testing purposes and does not support real card transactions. You can obtain your Sandbox API credentials from the [dashboard](https://dashboard.payout.com/api). ## Test Cards The following card numbers can be used in the sandbox environment with any valid expiration (i.e., in the future). Any other card number will be treated as an unsupported card. [block:parameters] { "data": { "h-0": "Number", "h-1": "Description", "0-0": "4111111111111111", "1-0": "4111111111111129", "0-1": "Successful tokenization and successful credits.", "1-1": "Successfully tokenizes but returns card_expired when crediting (regardless of the expiration date you specify).\n\nThis is useful to test when a previously tokenized card has since expired.", "2-0": "4111111111111137", "2-1": "Simulates successful tokenization (card will appear **ready**) but results in a **card_declined** error when crediting.", "3-0": "4111111111111145", "3-1": "Simulates successful tokenization (card will appear **ready**) but results in a **transaction_declined** error when crediting.\n\n*In the Live environment, this should be a small percentage of credits but can happen if the card is on a supported network but the specific bank is not prepared to handle the transaction type.*", "4-0": "4211111111111110", "4-1": "Simulates a successful asynchronous transaction. When crediting this card, it will return with a state of `scheduled`." }, "cols": 2, "rows": 5 } [/block] ## Test Bank Accounts The following bank account and routing numbers can be used in the sandbox environment. [block:parameters] { "data": { "h-0": "Account Number", "h-1": "ACH Routing Number", "h-2": "Description", "0-1": "120000003", "0-0": "111111111", "0-2": "Accepts test ACH deposits." }, "cols": 3, "rows": 1 } [/block] ## Billing Address Verification To test the different [billing address verification](doc:billing-address-verification) responses, use the following values. ### Street Address Test Values [block:parameters] { "data": { "h-0": "Value", "h-1": "Test trigger", "0-0": "`yes`", "1-0": "`no`", "2-0": "`n/a`", "0-1": "Any `line1` that does not match the conditions below.", "1-1": "If the `line1` value starts with `101` followed by any other characters.", "2-1": "If the `line1` value starts with `202` followed by any other characters." }, "cols": 2, "rows": 3 } [/block] ### Postal Code Test Values [block:parameters] { "data": { "h-0": "Value", "h-1": "Test trigger", "0-0": "`yes`", "1-0": "`no`", "2-0": "`n/a`", "0-1": "Any `postal_code` that does not match the conditions below.", "1-1": "If `postal_code` equals `10001`.", "2-1": "If `postal_code` equals `20002`." }, "cols": 2, "rows": 3 } [/block]
{"__v":3,"_id":"5668d665149b0b0d0078530b","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"To gain live access (i.e., production access), we'll need to collect some documents from you for compliance purposes.  If you're interested, please reach out to us at [apply@payout.com](mailto:apply@payout.com).\n\nOnce you've been granted access, you can obtain your live API credentials from the [dashboard](https://dashboard.payout.com/api) just as with your sandbox credentials.","category":"5452be95b7fa011600a75c4c","createdAt":"2015-12-10T01:33:25.575Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":3,"project":"53fba347e406d10c30ed5f61","slug":"live-access","sync_unique":"","title":"Live Access","type":"basic","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Live Access


To gain live access (i.e., production access), we'll need to collect some documents from you for compliance purposes. If you're interested, please reach out to us at [apply@payout.com](mailto:apply@payout.com). Once you've been granted access, you can obtain your live API credentials from the [dashboard](https://dashboard.payout.com/api) just as with your sandbox credentials.
To gain live access (i.e., production access), we'll need to collect some documents from you for compliance purposes. If you're interested, please reach out to us at [apply@payout.com](mailto:apply@payout.com). Once you've been granted access, you can obtain your live API credentials from the [dashboard](https://dashboard.payout.com/api) just as with your sandbox credentials.
{"__v":11,"_id":"5452be95b7fa011600a75c50","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[{"language":"json","code":"{}","name":"Success"},{"language":"json","code":"{}","name":"Failure"}]},"settings":"","try":true,"url":""},"body":"You're always welcome to use the raw HTTP API.  However, we provide some API libraries to simplify your integration.\n\nFor front-end tokenization of sensitive card data, see our [JavaScript](https://www.payout.com/page/javascript-library) Library.\n\nFor backend payment processing, we provide a [Ruby](https://www.payout.com/page/ruby-library) Library.\n\nIf you have another language that you would like support for, let us know at [support@payout.com](mailto:support@payout.com).","category":"5452be95b7fa011600a75c4c","createdAt":"2014-08-25T23:13:54.895Z","excerpt":"","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":4,"project":"53fba347e406d10c30ed5f61","slug":"general-details","sync_unique":"","title":"API Libraries","type":"basic","updates":[],"user":"5250b3ad5ac09b3564000005","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

API Libraries


You're always welcome to use the raw HTTP API. However, we provide some API libraries to simplify your integration. For front-end tokenization of sensitive card data, see our [JavaScript](https://www.payout.com/page/javascript-library) Library. For backend payment processing, we provide a [Ruby](https://www.payout.com/page/ruby-library) Library. If you have another language that you would like support for, let us know at [support@payout.com](mailto:support@payout.com).
You're always welcome to use the raw HTTP API. However, we provide some API libraries to simplify your integration. For front-end tokenization of sensitive card data, see our [JavaScript](https://www.payout.com/page/javascript-library) Library. For backend payment processing, we provide a [Ruby](https://www.payout.com/page/ruby-library) Library. If you have another language that you would like support for, let us know at [support@payout.com](mailto:support@payout.com).
{"__v":9,"_id":"5452be95b7fa011600a75c51","api":{"auth":"required","basic_auth":true,"examples":{"codes":[{"code":"curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/balance","language":"curl"},{"code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Balance.retrieve","language":"ruby"}]},"method":"get","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"balance\": 10000\n}","name":"Success"}]},"settings":"","try":false,"url":"/balance"},"body":"This endpoint can be used to programmatically retrieve the balance your company has with Payout (i.e., the funds available to send customers).\n\nNote that any credit that would bring your balance below 0 will be rejected.","category":"5452be95b7fa011600a75c4b","createdAt":"2014-08-25T23:17:15.978Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"is_link":false,"link_external":false,"link_url":"","order":0,"project":"53fba347e406d10c30ed5f61","slug":"get-balance","sync_unique":"","title":"/balance","type":"get","updates":[],"user":"5250b3ad5ac09b3564000005","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

get/balance


This endpoint can be used to programmatically retrieve the balance your company has with Payout (i.e., the funds available to send customers). Note that any credit that would bring your balance below 0 will be rejected.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint can be used to programmatically retrieve the balance your company has with Payout (i.e., the funds available to send customers). Note that any credit that would bring your balance below 0 will be rejected.
{"__v":0,"_id":"5452be95b7fa011600a75c52","api":{"auth":"required","basic_auth":false,"examples":{"codes":[{"language":"curl","code":"curl -X PUT https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/balance -d \"balance=1000000\""},{"language":"ruby","code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Balance.update(balance: 10_000_00)"}]},"method":"put","params":[{"_id":"543d9fe131ca981a00a6ffd4","required":false,"desc":"The amount in cents to set the balance to.","default":"","type":"int","name":"balance","in":"body"}],"results":{"codes":[{"language":"json","code":"{\n  \"balance\": 999999\n}","name":"Success"}]},"settings":"","try":false,"url":"/balance"},"body":"This endpoint is only accessible within the sandbox environment and allows you to set your balance so you can easily test the case of running out of money.\n\n***Testing Hint:*** To test the insufficient funds case when crediting a card, use the `test_insufficient_funds` flag in the credit endpoint instead of setting your balance to 0 with this endpoint.","category":"5452be95b7fa011600a75c4b","createdAt":"2014-08-25T23:19:58.256Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":1,"project":"53fba347e406d10c30ed5f61","slug":"set-balance","sync_unique":"","title":"/balance","type":"put","updates":[],"user":"5250b3ad5ac09b3564000005","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

put/balance


Body Params

balance:
integer
The amount in cents to set the balance to.
This endpoint is only accessible within the sandbox environment and allows you to set your balance so you can easily test the case of running out of money. ***Testing Hint:*** To test the insufficient funds case when crediting a card, use the `test_insufficient_funds` flag in the credit endpoint instead of setting your balance to 0 with this endpoint.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



This endpoint is only accessible within the sandbox environment and allows you to set your balance so you can easily test the case of running out of money. ***Testing Hint:*** To test the insufficient funds case when crediting a card, use the `test_insufficient_funds` flag in the credit endpoint instead of setting your balance to 0 with this endpoint.
{"__v":11,"_id":"5452c248b7fa011600a75c6a","api":{"auth":"never","basic_auth":false,"params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","try":true,"url":""},"body":"In order to simplify your [PCI DSS](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard) compliance, Payout provides card tokenization. This allows you to avoid sending card numbers to your servers, and instead send them directly to us from your client.  We'll give you a token which you can use later when you want to send money to the card.  This way, you don't need to worry about protecting your customers' sensitive cardholder data.  We'll do that for you!\n\n[Read more](http://www.payout.com/security) about how we protect your customers' data on the [security page](http://www.payout.com/security).\n\nWe recommend using our [JavaScript](https://www.payout.com/page/javascript-library) Library to handle tokenizing on your website.","category":"569933387465970d00650b84","createdAt":"2014-10-30T22:57:12.977Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"is_link":false,"link_external":false,"link_url":"","order":0,"project":"53fba347e406d10c30ed5f61","slug":"card-tokenization","sync_unique":"","title":"Tokenization","type":"basic","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Tokenization


In order to simplify your [PCI DSS](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard) compliance, Payout provides card tokenization. This allows you to avoid sending card numbers to your servers, and instead send them directly to us from your client. We'll give you a token which you can use later when you want to send money to the card. This way, you don't need to worry about protecting your customers' sensitive cardholder data. We'll do that for you! [Read more](http://www.payout.com/security) about how we protect your customers' data on the [security page](http://www.payout.com/security). We recommend using our [JavaScript](https://www.payout.com/page/javascript-library) Library to handle tokenizing on your website.
In order to simplify your [PCI DSS](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard) compliance, Payout provides card tokenization. This allows you to avoid sending card numbers to your servers, and instead send them directly to us from your client. We'll give you a token which you can use later when you want to send money to the card. This way, you don't need to worry about protecting your customers' sensitive cardholder data. We'll do that for you! [Read more](http://www.payout.com/security) about how we protect your customers' data on the [security page](http://www.payout.com/security). We recommend using our [JavaScript](https://www.payout.com/page/javascript-library) Library to handle tokenizing on your website.
{"__v":11,"_id":"56cbd4b3ca43550b00281216","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"If you provide a billing address when tokenizing a card or add a billing address to a previously tokenized card, we'll perform an address verification to make sure the street address and the postal code match the billing address on the card.  If the customer recently changed their billing address, it may take up to 24 hours for it to be reflected in our systems.\n\n## Verification Values\n[block:parameters]\n{\n  \"data\": {\n    \"0-0\": \"`yes`\",\n    \"0-1\": \"The street address / postal code matches the value on the card's billing address.\",\n    \"1-0\": \"`no`\",\n    \"1-1\": \"The street address / postal code does **not** match the value on the card's billing address.\",\n    \"2-0\": \"`n/a`\",\n    \"2-1\": \"We were not able to determine if the street address / postal code matches the card's billing address.\",\n    \"h-0\": \"Value\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 3\n}\n[/block]\n### Sandbox Testing\nTo test these different responses, see the [Sandbox Access](doc:sandbox-access) section above.","category":"569933387465970d00650b84","createdAt":"2016-02-23T03:40:35.232Z","excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"53fba347e406d10c30ed5f61","slug":"billing-address-verification","sync_unique":"","title":"Billing Address Verification","type":"basic","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Billing Address Verification


If you provide a billing address when tokenizing a card or add a billing address to a previously tokenized card, we'll perform an address verification to make sure the street address and the postal code match the billing address on the card. If the customer recently changed their billing address, it may take up to 24 hours for it to be reflected in our systems. ## Verification Values [block:parameters] { "data": { "0-0": "`yes`", "0-1": "The street address / postal code matches the value on the card's billing address.", "1-0": "`no`", "1-1": "The street address / postal code does **not** match the value on the card's billing address.", "2-0": "`n/a`", "2-1": "We were not able to determine if the street address / postal code matches the card's billing address.", "h-0": "Value", "h-1": "Description" }, "cols": 2, "rows": 3 } [/block] ### Sandbox Testing To test these different responses, see the [Sandbox Access](doc:sandbox-access) section above.
If you provide a billing address when tokenizing a card or add a billing address to a previously tokenized card, we'll perform an address verification to make sure the street address and the postal code match the billing address on the card. If the customer recently changed their billing address, it may take up to 24 hours for it to be reflected in our systems. ## Verification Values [block:parameters] { "data": { "0-0": "`yes`", "0-1": "The street address / postal code matches the value on the card's billing address.", "1-0": "`no`", "1-1": "The street address / postal code does **not** match the value on the card's billing address.", "2-0": "`n/a`", "2-1": "We were not able to determine if the street address / postal code matches the card's billing address.", "h-0": "Value", "h-1": "Description" }, "cols": 2, "rows": 3 } [/block] ### Sandbox Testing To test these different responses, see the [Sandbox Access](doc:sandbox-access) section above.
{"__v":6,"_id":"5452c622b7fa011600a75c8b","api":{"auth":"required","basic_auth":false,"examples":{"codes":[{"language":"curl","code":"curl -X POST https://$API_TOKEN:@sandbox.payout.com/v1/cards \\\n  -d \"name=John Smith\" \\\n  -d \"card_number=4111111111111111\" \\\n  -d \"exp_month=08\" \\\n  -d \"exp_year=19\""},{"code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\n# Normally, you'll want to do this from your front-end to avoid\n# sending card numbers to your servers, but this can be useful\n# for testing.\nPayout::Card.tokenize(\n  name: 'John Smith',\n  card_number: '4111111111111111',\n  exp_month: '08',\n  exp_year: '19'\n)","language":"ruby"},{"name":"JavaScript","language":"javascript","code":"// Initialize the JavaScript library.\nPayout.init('X1Kr7zLFW2H');\n// ...\nPayout.card.tokenize({\n  name: 'John Smith',\n  card_number: '4111111111111111',\n  exp_month: '08',\n  exp_year: '19'\n}, function(response) {\n  // Send response.token to your backend\n  // servers (but don't send the card number!)\n  console.log(response);\n});"}]},"method":"post","params":[{"_id":"5452c622b7fa011600a75c8f","ref":"","required":false,"desc":"The customers name (must be within 200 characters).","default":"","type":"string","name":"name","in":"body"},{"_id":"5452c622b7fa011600a75c8e","ref":"","required":false,"desc":"The full card number (must be between 15-16 digits).","default":"","type":"string","name":"card_number","in":"body"},{"_id":"5452c622b7fa011600a75c8d","ref":"","required":false,"desc":"2-digit expiry month.","default":"","type":"string","name":"exp_month","in":"body"},{"_id":"5452c622b7fa011600a75c8c","ref":"","required":false,"desc":"2-digit expiry year.","default":"","type":"string","name":"exp_year","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"token\": \"CTFNkgkInM4bBEkDAScg7cc1\",\n  \"state\": \"customer_info_required\",\n  \"last_four\": \"1111\",\n  \"brand\": \"visa\",\n  \"card_identifier\": \"CIfIj4fnqPa0Uwz\",\n  \"type\": \"debit\",\n  \"issuer\": \"SOME BANK, N.A.\",\n  \"country_code\": \"USA\",\n  \"created_at\": 1414711429\n}","language":"json","status":201},{"name":"Unsupported Card","code":"{\n  \"token\": \"CTdGYxy8sOMMk7AnVl5GnJkc\",\n  \"state\": \"unsupported\",\n  \"last_four\": \"1111\",\n  \"brand\": \"mastercard\",\n  \"created_at\": 1414711429\n}","language":"json","status":404},{"code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"name is missing\",\n    \"card_number is missing\",\n    \"exp_month is missing\",\n    \"exp_year is missing\"\n  ]\n}","language":"json","name":"Missing Params","status":400},{"code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"card_number is invalid\",\n    \"exp_month is invalid\",\n    \"exp_year is invalid\"\n  ]\n}","language":"json","status":400,"name":"Invalid Params"},{"code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"card_number must be a valid card number\"\n  ]\n}","language":"json","status":400,"name":"Luhn Check Failure"},{"code":"{\n  \"error\": \"card_expired\"\n}","language":"json","status":400,"name":"Expired Card"}]},"settings":"","try":false,"url":"/cards"},"body":"Tokenize the card's number and expiration information.\n\n## Authentication\nWhen authenticating to this endpoint, you only need to send your API token.  You don't need to send your API secret as the password.  Make sure you never expose your API secret to on your client!  It grants access to all other endpoints.\n\n## Status\nIf the card is supported you'll receive a \"customer_info_required\" status. This means the card is supported, but we're awaiting information about the customer before we approve it for credits. This is to satisfy our own compliance requirements.\n\nSee the customer endpoint below for details.\n\n## Testing\nIn the sandbox environment, you can simulate a successful transaction using the card number `4111111111111111`.  The expiration doesn't matter, as long as it's in the future.\n\n## JavaScript Library\nUse our [JavaScript Library](page:javascript-library) to simplify tokenizing card numbers from you website.","category":"569933387465970d00650b84","createdAt":"2014-10-30T23:13:38.580Z","editedParams":true,"editedParams2":true,"excerpt":"Tokenize a card.","githubsync":"","hidden":false,"isReference":false,"is_link":false,"link_external":false,"link_url":"","order":2,"project":"53fba347e406d10c30ed5f61","slug":"card-tokenize","sync_unique":"","title":"/cards","type":"post","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

post/cards

Tokenize a card.

Body Params

name:
string
The customers name (must be within 200 characters).
card_number:
string
The full card number (must be between 15-16 digits).
exp_month:
string
2-digit expiry month.
exp_year:
string
2-digit expiry year.
Tokenize the card's number and expiration information. ## Authentication When authenticating to this endpoint, you only need to send your API token. You don't need to send your API secret as the password. Make sure you never expose your API secret to on your client! It grants access to all other endpoints. ## Status If the card is supported you'll receive a "customer_info_required" status. This means the card is supported, but we're awaiting information about the customer before we approve it for credits. This is to satisfy our own compliance requirements. See the customer endpoint below for details. ## Testing In the sandbox environment, you can simulate a successful transaction using the card number `4111111111111111`. The expiration doesn't matter, as long as it's in the future. ## JavaScript Library Use our [JavaScript Library](page:javascript-library) to simplify tokenizing card numbers from you website.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Tokenize the card's number and expiration information. ## Authentication When authenticating to this endpoint, you only need to send your API token. You don't need to send your API secret as the password. Make sure you never expose your API secret to on your client! It grants access to all other endpoints. ## Status If the card is supported you'll receive a "customer_info_required" status. This means the card is supported, but we're awaiting information about the customer before we approve it for credits. This is to satisfy our own compliance requirements. See the customer endpoint below for details. ## Testing In the sandbox environment, you can simulate a successful transaction using the card number `4111111111111111`. The expiration doesn't matter, as long as it's in the future. ## JavaScript Library Use our [JavaScript Library](page:javascript-library) to simplify tokenizing card numbers from you website.
{"__v":14,"_id":"5452c8e1bcd6751000955384","api":{"auth":"required","basic_auth":false,"examples":{"codes":[]},"method":"get","params":[{"_id":"5699952ccb127f0d003cc1a4","default":"","desc":"A token returned by the card tokenization endpoint.","name":"token","ref":"","required":false,"type":"string","in":"path"}],"results":{"codes":[{"name":"Ready","code":"{\n  \"token\": \"CTD3JGxc72M27TinoHuUgROL\",\n  \"state\": \"ready\",\n  \"last_four\": \"1111\",\n  \"brand\": \"visa\",\n  \"created_at\": 1414708839\n}","language":"json","status":200},{"name":"Customer Info Required","code":"{\n    \"token\": \"CTWsT8GTe6hq9DYqb4jZ7Vl1\",\n    \"state\": \"customer_info_required\",\n    \"last_four\": \"1111\",\n    \"brand\": \"visa\",\n    \"billing_address\": {\n        \"line1\": \"1234 Some Rd.\",\n        \"city\": \"San Francisco\",\n        \"state\": \"CA\",\n        \"postal_code\": \"94104\"\n    },\n    \"street_address_verified\": \"yes\",\n    \"postal_code_verified\": \"yes\",\n    \"created_at\": 1456198404\n}","language":"json","status":200},{"name":null,"status":404,"language":"json","code":"{\n  \"error\": \"no_such_card\"\n}"}]},"settings":"","try":false,"url":"/cards/:token"},"body":"[block:textarea]\n{\n  \"text\": \"## Request\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"language\": \"curl\",\n      \"code\": \"curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL\"\n    },\n    {\n      \"language\": \"ruby\",\n      \"code\": \"require 'payout'\\nPayout.api_url = ENV['PAYOUT_API_URL']\\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\\n\\nPayout::Card.retrieve('CTD3JGxc72M27TinoHuUgROL')\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n  \"text\": \"## Results\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"name\": 200,\n      \"code\": \"{\\n  \\\"token\\\": \\\"CTD3JGxc72M27TinoHuUgROL\\\",\\n  \\\"state\\\": \\\"ready\\\",\\n  \\\"last_four\\\": \\\"1111\\\",\\n  \\\"brand\\\": \\\"visa\\\",\\n  \\\"created_at\\\": 1414708839\\n}\",\n      \"language\": \"json\",\n      \"status\": 200\n    },\n    {\n      \"name\": 200,\n      \"code\": \"{\\n    \\\"token\\\": \\\"CTWsT8GTe6hq9DYqb4jZ7Vl1\\\",\\n    \\\"state\\\": \\\"customer_info_required\\\",\\n    \\\"last_four\\\": \\\"1111\\\",\\n    \\\"brand\\\": \\\"visa\\\",\\n    \\\"billing_address\\\": {\\n        \\\"line1\\\": \\\"1234 Some Rd.\\\",\\n        \\\"city\\\": \\\"San Francisco\\\",\\n        \\\"state\\\": \\\"CA\\\",\\n        \\\"postal_code\\\": \\\"94104\\\"\\n    },\\n    \\\"street_address_verified\\\": \\\"yes\\\",\\n    \\\"postal_code_verified\\\": \\\"yes\\\",\\n    \\\"created_at\\\": 1456198404\\n}\\n\",\n      \"language\": \"json\",\n      \"status\": 200\n    },\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"no_such_card\\\"\\n}\",\n      \"language\": \"json\",\n      \"status\": 404,\n      \"name\": 404\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\nYou may want to check the status of card after you've generated it. This endpoint allows you to do just that.\n\n##Possible card states: \n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"State Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"`pending`\",\n    \"0-1\": \"We're still gathering information on the card, and have yet to determined if we support it. Typically, you'll never see this state.\",\n    \"1-0\": \"`unsupported`\",\n    \"1-1\": \"We're not able to issue a credit to this card.\",\n    \"2-0\": \"`customer_info_required`\",\n    \"2-1\": \"We require information about the customer before this card may be credited.  Note that this status also implies that the card is supported.\",\n    \"3-0\": \"`ready`\",\n    \"3-1\": \"The card is supported and may now be credited.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","category":"569933387465970d00650b84","createdAt":"2014-10-30T23:25:21.865Z","editedParams":true,"editedParams2":true,"excerpt":"Retrieve the card token.","githubsync":"","hidden":false,"isReference":false,"is_link":false,"link_external":false,"link_url":"","order":3,"project":"53fba347e406d10c30ed5f61","slug":"retrieve-card","sync_unique":"","title":"/cards/:token","type":"get","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

get/cards/:token

Retrieve the card token.

Path Params

token:
string
A token returned by the card tokenization endpoint.
[block:textarea] { "text": "## Request", "sidebar": true } [/block] [block:code] { "codes": [ { "language": "curl", "code": "curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL" }, { "language": "ruby", "code": "require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Card.retrieve('CTD3JGxc72M27TinoHuUgROL')" } ], "sidebar": true } [/block] [block:textarea] { "text": "## Results", "sidebar": true } [/block] [block:code] { "codes": [ { "name": 200, "code": "{\n \"token\": \"CTD3JGxc72M27TinoHuUgROL\",\n \"state\": \"ready\",\n \"last_four\": \"1111\",\n \"brand\": \"visa\",\n \"created_at\": 1414708839\n}", "language": "json", "status": 200 }, { "name": 200, "code": "{\n \"token\": \"CTWsT8GTe6hq9DYqb4jZ7Vl1\",\n \"state\": \"customer_info_required\",\n \"last_four\": \"1111\",\n \"brand\": \"visa\",\n \"billing_address\": {\n \"line1\": \"1234 Some Rd.\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94104\"\n },\n \"street_address_verified\": \"yes\",\n \"postal_code_verified\": \"yes\",\n \"created_at\": 1456198404\n}\n", "language": "json", "status": 200 }, { "code": "{\n \"error\": \"no_such_card\"\n}", "language": "json", "status": 404, "name": 404 } ], "sidebar": true } [/block] You may want to check the status of card after you've generated it. This endpoint allows you to do just that. ##Possible card states: [block:parameters] { "data": { "h-0": "State Name", "h-1": "Description", "0-0": "`pending`", "0-1": "We're still gathering information on the card, and have yet to determined if we support it. Typically, you'll never see this state.", "1-0": "`unsupported`", "1-1": "We're not able to issue a credit to this card.", "2-0": "`customer_info_required`", "2-1": "We require information about the customer before this card may be credited. Note that this status also implies that the card is supported.", "3-0": "`ready`", "3-1": "The card is supported and may now be credited." }, "cols": 2, "rows": 4 } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:textarea] { "text": "## Request", "sidebar": true } [/block] [block:code] { "codes": [ { "language": "curl", "code": "curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL" }, { "language": "ruby", "code": "require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Card.retrieve('CTD3JGxc72M27TinoHuUgROL')" } ], "sidebar": true } [/block] [block:textarea] { "text": "## Results", "sidebar": true } [/block] [block:code] { "codes": [ { "name": 200, "code": "{\n \"token\": \"CTD3JGxc72M27TinoHuUgROL\",\n \"state\": \"ready\",\n \"last_four\": \"1111\",\n \"brand\": \"visa\",\n \"created_at\": 1414708839\n}", "language": "json", "status": 200 }, { "name": 200, "code": "{\n \"token\": \"CTWsT8GTe6hq9DYqb4jZ7Vl1\",\n \"state\": \"customer_info_required\",\n \"last_four\": \"1111\",\n \"brand\": \"visa\",\n \"billing_address\": {\n \"line1\": \"1234 Some Rd.\",\n \"city\": \"San Francisco\",\n \"state\": \"CA\",\n \"postal_code\": \"94104\"\n },\n \"street_address_verified\": \"yes\",\n \"postal_code_verified\": \"yes\",\n \"created_at\": 1456198404\n}\n", "language": "json", "status": 200 }, { "code": "{\n \"error\": \"no_such_card\"\n}", "language": "json", "status": 404, "name": 404 } ], "sidebar": true } [/block] You may want to check the status of card after you've generated it. This endpoint allows you to do just that. ##Possible card states: [block:parameters] { "data": { "h-0": "State Name", "h-1": "Description", "0-0": "`pending`", "0-1": "We're still gathering information on the card, and have yet to determined if we support it. Typically, you'll never see this state.", "1-0": "`unsupported`", "1-1": "We're not able to issue a credit to this card.", "2-0": "`customer_info_required`", "2-1": "We require information about the customer before this card may be credited. Note that this status also implies that the card is supported.", "3-0": "`ready`", "3-1": "The card is supported and may now be credited." }, "cols": 2, "rows": 4 } [/block]
{"__v":2,"_id":"56cbd1a8b4cbcf0b004a5db8","api":{"auth":"required","examples":{"codes":[]},"method":"put","params":[{"_id":"56cbd1a8b4cbcf0b004a5db9","required":false,"desc":"A token returned by the card tokenization endpoint.","default":"","type":"string","name":"token","in":"path"},{"_id":"56cbd2148df25d0b00e8d753","default":"optional","desc":"The name on the card (must be within 200 characters).","name":"name","required":false,"type":"string","in":"body"},{"_id":"56cbd2148df25d0b00e8d752","default":"optional","desc":"2-digit expiry month.","name":"exp_month","required":false,"type":"string","in":"body"},{"_id":"56cbd2148df25d0b00e8d751","default":"optional","desc":"2-digit expiry year.","name":"exp_year","required":false,"type":"string","in":"body"},{"_id":"56cbd2c18df25d0b00e8d759","default":"required if other billing_address fields specified","desc":"First line of the billing address. Maximum 200 characters.","name":"billing_address[line1]","required":false,"type":"string","in":"body"},{"_id":"56cbd2c18df25d0b00e8d758","default":"optional","desc":"Second line of the billing address (e.g., Apt or Suite number). Maximum 200 characters.","name":"billing_address[line2]","required":false,"type":"string","in":"body"},{"_id":"56cbd2c18df25d0b00e8d757","default":"required if other billing_address fields specified","desc":"Maximum 100 characters.","name":"billing_address[city]","required":false,"type":"string","in":"body"},{"_id":"56cbd2c18df25d0b00e8d756","default":"required if other billing_address fields specified","desc":"2-character (capitalized) state code.","name":"billing_address[state]","required":false,"type":"string","in":"body"},{"_id":"56cbd2c18df25d0b00e8d755","default":"required if other billing_address fields specified","desc":"5-digit postal code.","name":"billing_address[postal_code]","required":false,"type":"string","in":"body"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n    \"token\": \"CTWsT8GTe6hq9DYqb4jZ7Vl1\",\n    \"state\": \"customer_info_required\",\n    \"last_four\": \"1111\",\n    \"brand\": \"visa\",\n    \"billing_address\": {\n        \"line1\": \"1234 Some Rd.\",\n        \"city\": \"San Francisco\",\n        \"state\": \"CA\",\n        \"postal_code\": \"94104\"\n    },\n    \"street_address_verified\": \"yes\",\n    \"postal_code_verified\": \"yes\",\n    \"created_at\": 1456198404\n}","name":""},{"status":400,"language":"json","code":"{\n  \"error\": \"card_number_not_allowed\"\n}","name":"card_number cannot be changed"}]},"settings":"","url":"/cards/:token"},"body":"","category":"569933387465970d00650b84","createdAt":"2016-02-23T03:27:36.789Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":4,"project":"53fba347e406d10c30ed5f61","slug":"card-update","sync_unique":"","title":"/cards/:token","type":"put","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

put/cards/:token


Path Params

token:
string
A token returned by the card tokenization endpoint.

Body Params

name:
stringoptional
The name on the card (must be within 200 characters).
exp_month:
stringoptional
2-digit expiry month.
exp_year:
stringoptional
2-digit expiry year.
billing_address[line1]:
stringrequired if other billing_address fields specified
First line of the billing address. Maximum 200 characters.
billing_address[line2]:
stringoptional
Second line of the billing address (e.g., Apt or Suite number). Maximum 200 characters.
billing_address[city]:
stringrequired if other billing_address fields specified
Maximum 100 characters.
billing_address[state]:
stringrequired if other billing_address fields specified
2-character (capitalized) state code.
billing_address[postal_code]:
stringrequired if other billing_address fields specified
5-digit postal code.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



{"__v":2,"_id":"5452cbbfbcd675100095538f","api":{"auth":"required","basic_auth":false,"examples":{"codes":[{"language":"curl","code":"curl -X PUT https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL/customer -d \"name=John Smith\" -d \"address_line1=1 Stockton St.\" -d \"address_city=San Francisco\" -d \"address_state=CA\" -d \"address_zip=94108\""},{"language":"ruby","code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Card.update_customer(\n  card_token: 'CTD3JGxc72M27TinoHuUgROL',\n  name: 'John Smith',\n  address_line1: '1 Stockton St.',\n  address_city: 'San Francisco',\n  address_state: 'CA',\n  address_zip: '94108'\n)"}]},"method":"put","params":[{"_id":"5699957754d7db17000eea8c","default":"","desc":"A token returned by the card tokenization endpoint.","name":"token","required":false,"type":"string","in":"path"},{"_id":"5452cda0b7fa011600a75ccc","required":false,"desc":"Customer's full name if different from name on card.","default":"defaults to the name on the card","type":"string","name":"name","in":"body"},{"_id":"5452cbbfbcd6751000955394","default":"","desc":"First line of the mailing address. Maximum 200 characters.","name":"address_line1","required":false,"type":"string","in":"body"},{"_id":"5452cbbfbcd6751000955393","default":"optional","desc":"Second line of the mailing address. Maximum 200 characters.","name":"address_line2","required":false,"type":"string","in":"body"},{"_id":"5452cbbfbcd6751000955392","required":false,"desc":"Maximum 100 characters.","default":"","type":"string","name":"address_city","in":"body"},{"_id":"5452cbbfbcd6751000955391","required":false,"desc":"2-character state code.","default":"","type":"string","name":"address_state","in":"body"},{"_id":"5452cbbfbcd6751000955390","required":false,"desc":"5-digit postal code.","default":"","type":"string","name":"address_zip","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"name\": \"John Smith\",\n  \"address_line1\": \"1 Stockton St.\",\n  \"address_line2\": null,\n  \"address_city\": \"San Francisco\",\n  \"address_state\": \"CA\",\n  \"address_zip\": \"94108\",\n  \"created_at\": 1414783303\n}","language":"json","status":200},{"name":"","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"address_line1 is missing\",\n    \"address_city is missing\",\n    \"address_state is missing\",\n    \"address_zip is missing\"\n  ]\n}","language":"json","status":400},{"name":"Invalid Params","status":400,"language":"json","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"address_line1 must be at most 200 characters long\",\n    \"address_line2 must be at most 200 characters long\",\n    \"address_city must be at most 100 characters long\",\n    \"address_state is invalid\",\n    \"address_zip is invalid\"\n  ]\n}"}]},"settings":"","try":false,"url":"/cards/:token/customer"},"body":"Before you can credit a card, you must provide additional information on the recipient. This is for our own compliance purposes.\n\nWe're required to collect:\n \n * The customer's full legal name if it's different from the name on the card.\n * The customer's mailing address.\n \nThis endpoint allows you to attach the customer's information to the card token from your back-end.","category":"569933387465970d00650b84","createdAt":"2014-10-30T23:37:35.539Z","editedParams":true,"editedParams2":true,"excerpt":"Provide required customer information.","githubsync":"","hidden":false,"is_link":false,"link_external":false,"link_url":"","order":5,"project":"53fba347e406d10c30ed5f61","slug":"card-customer","sync_unique":"","title":"/cards/:token/customer","type":"put","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

put/cards/:token/customer

Provide required customer information.

Path Params

token:
string
A token returned by the card tokenization endpoint.

Body Params

name:
stringdefaults to the name on the card
Customer's full name if different from name on card.
address_line1:
string
First line of the mailing address. Maximum 200 characters.
address_line2:
stringoptional
Second line of the mailing address. Maximum 200 characters.
address_city:
string
Maximum 100 characters.
address_state:
string
2-character state code.
address_zip:
string
5-digit postal code.
Before you can credit a card, you must provide additional information on the recipient. This is for our own compliance purposes. We're required to collect: * The customer's full legal name if it's different from the name on the card. * The customer's mailing address. This endpoint allows you to attach the customer's information to the card token from your back-end.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Before you can credit a card, you must provide additional information on the recipient. This is for our own compliance purposes. We're required to collect: * The customer's full legal name if it's different from the name on the card. * The customer's mailing address. This endpoint allows you to attach the customer's information to the card token from your back-end.
{"__v":8,"_id":"5452d028bcd67510009553aa","api":{"auth":"required","basic_auth":false,"examples":{"codes":[]},"method":"post","params":[{"_id":"5699958694a308190081fec1","default":"","desc":"A token returned by the card tokenization endpoint.","name":"token","ref":"","required":false,"type":"string","in":"path"},{"_id":"5452d3339000090800952146","default":"","desc":"Amount in cents (maximum value of 200000).","name":"amount","ref":"","required":false,"type":"int","in":"body"},{"_id":"55023d7c64d596210042de76","default":"false","desc":"Simulate the insufficient funds error.","name":"test_insufficient_funds","ref":"","required":false,"type":"string","in":"body"},{"_id":"56707a5c6995210d003aad6d","default":"optional","desc":"You may optionally specify your own reference_id. If specified, it must be unique for all payments made on your account. This can also be used to lookup transactions in case your connection to us times out. Must be 1 to 80 alphanumeric characters + underscores + dashes (\"-\").","name":"reference_id","ref":"","required":false,"type":"string","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"token\": \"CC3hXUSMgMpasvp\",\n  \"state\": \"cleared\",\n  \"amount\": 100,\n  \"created_at\": 1414714141\n}","language":"json","status":201},{"name":"Insufficient Funds","code":"{\n  \"error\": \"insufficient_funds\"\n}","language":"json","status":403},{"name":"Card Expired","status":406,"language":"json","code":"{\n  \"token\": \"CChoXaEtL7lvFcd\",\n  \"state\": \"failed\",\n  \"error\": \"card_expired\",\n  \"amount\": 10,\n  \"created_at\": 1450110979\n}"},{"code":"{\n  \"token\": \"CCkShoH5UBYqqh5\",\n  \"state\": \"failed\",\n  \"error\": \"card_declined\",\n  \"amount\": 100,\n  \"created_at\": 1450110948\n}","language":"json","name":"Card Declined","status":406},{"status":403,"name":"Card Unsupported","language":"json","code":"{\n  \"error\": \"unsupported_card\"\n}"},{"code":"{\n  \"token\": \"CCohTHp6YP228cB\",\n  \"state\": \"failed\",\n  \"error\": \"transaction_declined\",\n  \"amount\": 100,\n  \"created_at\": 1450110834\n}","language":"json","name":"Transaction Declined","status":406},{"name":"Invalid Input","status":400,"language":"text","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"amount must be at least 10 and no more than 200000\",\n    \"reference_id is invalid\"\n  ]\n}"},{"name":"Duplicate Reference Id","status":400,"language":"json","code":"{\n  \"error\": \"duplicate_reference_id\"\n}"}]},"settings":"","try":false,"url":"/cards/:token/credits"},"body":"[block:textarea]\n{\n  \"text\": \"## Request\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"language\": \"curl\",\n      \"code\": \"curl -X POST https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL/credits -d \\\"amount=100\\\" -d \\\"reference_id=my_transaction_id\\\"\"\n    },\n    {\n      \"language\": \"ruby\",\n      \"code\": \"require 'payout'\\nPayout.api_url = ENV['PAYOUT_API_URL']\\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\\n\\nPayout::Card.credit(\\n  card_token: 'CTD3JGxc72M27TinoHuUgROL',\\n  amount: 100,\\n  reference_id: 'my_transaction_id'\\n)\"\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\n\n[block:textarea]\n{\n  \"text\": \"## Results\",\n  \"sidebar\": true\n}\n[/block]\n\n[block:code]\n{\n  \"codes\": [\n    {\n      \"name\": 201,\n      \"code\": \"{\\n  \\\"token\\\": \\\"CC3hXUSMgMpasvp\\\",\\n  \\\"state\\\": \\\"cleared\\\",\\n  \\\"amount\\\": 100,\\n  \\\"created_at\\\": 1414714141\\n}\",\n      \"language\": \"json\",\n      \"status\": 201\n    },\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"insufficient_funds\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": 403,\n      \"status\": 403\n    },\n    {\n      \"code\": \"{\\n  \\\"token\\\": \\\"CChoXaEtL7lvFcd\\\",\\n  \\\"state\\\": \\\"failed\\\",\\n  \\\"error\\\": \\\"card_expired\\\",\\n  \\\"amount\\\": 10,\\n  \\\"created_at\\\": 1450110979\\n}\",\n      \"language\": \"json\",\n      \"status\": 406,\n      \"name\": 406\n    },\n    {\n      \"code\": \"{\\n  \\\"token\\\": \\\"CCkShoH5UBYqqh5\\\",\\n  \\\"state\\\": \\\"failed\\\",\\n  \\\"error\\\": \\\"card_declined\\\",\\n  \\\"amount\\\": 100,\\n  \\\"created_at\\\": 1450110948\\n}\",\n      \"language\": \"json\",\n      \"status\": 406,\n      \"name\": 406\n    },\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"unsupported_card\\\"\\n}\",\n      \"language\": \"json\",\n      \"name\": 403,\n      \"status\": 403\n    },\n    {\n      \"code\": \"{\\n  \\\"token\\\": \\\"CCohTHp6YP228cB\\\",\\n  \\\"state\\\": \\\"failed\\\",\\n  \\\"error\\\": \\\"transaction_declined\\\",\\n  \\\"amount\\\": 100,\\n  \\\"created_at\\\": 1450110834\\n}\",\n      \"language\": \"json\",\n      \"status\": 406,\n      \"name\": 406\n    },\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"validation_errors\\\",\\n  \\\"validation_errors\\\": [\\n    \\\"amount must be at least 10 and no more than 200000\\\",\\n    \\\"reference_id is invalid\\\"\\n  ]\\n}\",\n      \"language\": \"json\",\n      \"status\": 400,\n      \"name\": 400\n    },\n    {\n      \"code\": \"{\\n  \\\"error\\\": \\\"duplicate_reference_id\\\"\\n}\",\n      \"language\": \"json\",\n      \"status\": 400,\n      \"name\": 400\n    }\n  ],\n  \"sidebar\": true\n}\n[/block]\nPerforms a credit to the card.  The maximum value for an individual credit is $2,000.00. Note that many credits will clear synchronously, but some will be returned as \"scheduled\", which indicates that we have scheduled the payment with the appropriate banking network, but that the transaction has not yet posted to the customer's account.\n\nPlease allow up to 20 seconds to receive a response from this endpoint, although normally you should receive a response in less than 5 seconds.","category":"569933387465970d00650b84","createdAt":"2014-10-30T23:56:24.223Z","editedParams":true,"editedParams2":true,"excerpt":"Initiate a credit to the card associated with the card token.","githubsync":"","hidden":false,"isReference":false,"is_link":false,"link_external":false,"link_url":"","order":6,"project":"53fba347e406d10c30ed5f61","slug":"card-credit","sync_unique":"","title":"/cards/:token/credits","type":"post","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

post/cards/:token/credits

Initiate a credit to the card associated with the card token.

Path Params

token:
string
A token returned by the card tokenization endpoint.

Body Params

amount:
integer
Amount in cents (maximum value of 200000).
test_insufficient_funds:
stringfalse
Simulate the insufficient funds error.
reference_id:
stringoptional
You may optionally specify your own reference_id. If specified, it must be unique for all payments made on your account. This can also be used to lookup transactions in case your connection to us times out. Must be 1 to 80 alphanumeric characters + underscores + dashes ("-").
[block:textarea] { "text": "## Request", "sidebar": true } [/block] [block:code] { "codes": [ { "language": "curl", "code": "curl -X POST https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL/credits -d \"amount=100\" -d \"reference_id=my_transaction_id\"" }, { "language": "ruby", "code": "require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Card.credit(\n card_token: 'CTD3JGxc72M27TinoHuUgROL',\n amount: 100,\n reference_id: 'my_transaction_id'\n)" } ], "sidebar": true } [/block] [block:textarea] { "text": "## Results", "sidebar": true } [/block] [block:code] { "codes": [ { "name": 201, "code": "{\n \"token\": \"CC3hXUSMgMpasvp\",\n \"state\": \"cleared\",\n \"amount\": 100,\n \"created_at\": 1414714141\n}", "language": "json", "status": 201 }, { "code": "{\n \"error\": \"insufficient_funds\"\n}", "language": "json", "name": 403, "status": 403 }, { "code": "{\n \"token\": \"CChoXaEtL7lvFcd\",\n \"state\": \"failed\",\n \"error\": \"card_expired\",\n \"amount\": 10,\n \"created_at\": 1450110979\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"token\": \"CCkShoH5UBYqqh5\",\n \"state\": \"failed\",\n \"error\": \"card_declined\",\n \"amount\": 100,\n \"created_at\": 1450110948\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"error\": \"unsupported_card\"\n}", "language": "json", "name": 403, "status": 403 }, { "code": "{\n \"token\": \"CCohTHp6YP228cB\",\n \"state\": \"failed\",\n \"error\": \"transaction_declined\",\n \"amount\": 100,\n \"created_at\": 1450110834\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"error\": \"validation_errors\",\n \"validation_errors\": [\n \"amount must be at least 10 and no more than 200000\",\n \"reference_id is invalid\"\n ]\n}", "language": "json", "status": 400, "name": 400 }, { "code": "{\n \"error\": \"duplicate_reference_id\"\n}", "language": "json", "status": 400, "name": 400 } ], "sidebar": true } [/block] Performs a credit to the card. The maximum value for an individual credit is $2,000.00. Note that many credits will clear synchronously, but some will be returned as "scheduled", which indicates that we have scheduled the payment with the appropriate banking network, but that the transaction has not yet posted to the customer's account. Please allow up to 20 seconds to receive a response from this endpoint, although normally you should receive a response in less than 5 seconds.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



[block:textarea] { "text": "## Request", "sidebar": true } [/block] [block:code] { "codes": [ { "language": "curl", "code": "curl -X POST https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/cards/CTD3JGxc72M27TinoHuUgROL/credits -d \"amount=100\" -d \"reference_id=my_transaction_id\"" }, { "language": "ruby", "code": "require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Card.credit(\n card_token: 'CTD3JGxc72M27TinoHuUgROL',\n amount: 100,\n reference_id: 'my_transaction_id'\n)" } ], "sidebar": true } [/block] [block:textarea] { "text": "## Results", "sidebar": true } [/block] [block:code] { "codes": [ { "name": 201, "code": "{\n \"token\": \"CC3hXUSMgMpasvp\",\n \"state\": \"cleared\",\n \"amount\": 100,\n \"created_at\": 1414714141\n}", "language": "json", "status": 201 }, { "code": "{\n \"error\": \"insufficient_funds\"\n}", "language": "json", "name": 403, "status": 403 }, { "code": "{\n \"token\": \"CChoXaEtL7lvFcd\",\n \"state\": \"failed\",\n \"error\": \"card_expired\",\n \"amount\": 10,\n \"created_at\": 1450110979\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"token\": \"CCkShoH5UBYqqh5\",\n \"state\": \"failed\",\n \"error\": \"card_declined\",\n \"amount\": 100,\n \"created_at\": 1450110948\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"error\": \"unsupported_card\"\n}", "language": "json", "name": 403, "status": 403 }, { "code": "{\n \"token\": \"CCohTHp6YP228cB\",\n \"state\": \"failed\",\n \"error\": \"transaction_declined\",\n \"amount\": 100,\n \"created_at\": 1450110834\n}", "language": "json", "status": 406, "name": 406 }, { "code": "{\n \"error\": \"validation_errors\",\n \"validation_errors\": [\n \"amount must be at least 10 and no more than 200000\",\n \"reference_id is invalid\"\n ]\n}", "language": "json", "status": 400, "name": 400 }, { "code": "{\n \"error\": \"duplicate_reference_id\"\n}", "language": "json", "status": 400, "name": 400 } ], "sidebar": true } [/block] Performs a credit to the card. The maximum value for an individual credit is $2,000.00. Note that many credits will clear synchronously, but some will be returned as "scheduled", which indicates that we have scheduled the payment with the appropriate banking network, but that the transaction has not yet posted to the customer's account. Please allow up to 20 seconds to receive a response from this endpoint, although normally you should receive a response in less than 5 seconds.
{"__v":4,"_id":"569972c6cb127f0d003cc176","api":{"auth":"required","params":[],"results":{"codes":[{"status":200,"language":"json","code":"{}","name":""},{"status":400,"language":"json","code":"{}","name":""}]},"settings":"","url":""},"body":"Unlike with card holder data, there are no industry requirements for securing bank account numbers. However, at Payout we take the privacy of your customers seriously and encrypt all customer data according to the [PCI Data Security Standard](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard).\n\n[Read more](http://docs.payout.com/v1/page/security) about how we protect your customers' data on the [security page](http://docs.payout.com/v1/page/security).","category":"569972ac03721e0d0043a497","createdAt":"2016-01-15T22:29:26.199Z","excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":0,"project":"53fba347e406d10c30ed5f61","slug":"bank-account-tokenization","sync_unique":"","title":"Tokenization","type":"basic","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

Tokenization


Unlike with card holder data, there are no industry requirements for securing bank account numbers. However, at Payout we take the privacy of your customers seriously and encrypt all customer data according to the [PCI Data Security Standard](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). [Read more](http://docs.payout.com/v1/page/security) about how we protect your customers' data on the [security page](http://docs.payout.com/v1/page/security).
Unlike with card holder data, there are no industry requirements for securing bank account numbers. However, at Payout we take the privacy of your customers seriously and encrypt all customer data according to the [PCI Data Security Standard](http://en.wikipedia.org/wiki/Payment_Card_Industry_Data_Security_Standard). [Read more](http://docs.payout.com/v1/page/security) about how we protect your customers' data on the [security page](http://docs.payout.com/v1/page/security).
{"__v":0,"_id":"56997712113a901900ef8fb0","api":{"auth":"required","examples":{"codes":[]},"method":"post","params":[{"_id":"56997712113a901900ef8fb5","default":"","desc":"Name on the bank account.","name":"name","ref":"","required":false,"type":"string","in":"body"},{"_id":"56997712113a901900ef8fb4","default":"","desc":"The account number for the account.","name":"account_number","ref":"","required":false,"type":"string","in":"body"},{"_id":"56997712113a901900ef8fb3","default":"","desc":"The routing number for the account required for ACH transactions. This is the routing number that appears on checks.","name":"ach_routing_number","ref":"","required":false,"type":"string","in":"body"},{"_id":"56997712113a901900ef8fb2","default":"checking","desc":"The type of the account (i.e., \"checking\" or \"savings\").","name":"account_type","ref":"","required":false,"type":"string","in":"body"},{"_id":"56997712113a901900ef8fb1","default":"personal","desc":"Either \"personal\" or \"business\".","name":"account_class","ref":"","required":false,"type":"string","in":"body"}],"results":{"codes":[{"status":201,"language":"json","code":"{\n  \"token\": \"BTKm2h2Lot9gK9lGoTMwxMxi\",\n  \"state\": \"customer_info_required\",\n  \"created_at\": 1452897874\n}","name":""},{"status":400,"language":"json","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"ach_routing_number must be a valid routing number\"\n  ]\n}","name":""},{"status":400,"language":"json","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"name is missing\"\n  ]\n}"}]},"settings":"","url":"/bank_accounts"},"body":"Tokenizes a sensitive bank account details.\n\n## Authentication\nWhen authenticating to this endpoint, you only need to send your API token.  You don't need to send your API secret as the password.  Make sure you never expose your API secret to on your client!  It grants access to all other endpoints.\n\n## Testing\nIn the sandbox environment, you can simulate a successful ACH deposit using the account number `111111111` and routing number `120000003`.","category":"569972ac03721e0d0043a497","createdAt":"2016-01-15T22:47:46.828Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":1,"project":"53fba347e406d10c30ed5f61","slug":"bank-account-tokenize","sync_unique":"","title":"/bank_accounts","type":"post","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

post/bank_accounts


Body Params

name:
string
Name on the bank account.
account_number:
string
The account number for the account.
ach_routing_number:
string
The routing number for the account required for ACH transactions. This is the routing number that appears on checks.
account_type:
stringchecking
The type of the account (i.e., "checking" or "savings").
account_class:
stringpersonal
Either "personal" or "business".
Tokenizes a sensitive bank account details. ## Authentication When authenticating to this endpoint, you only need to send your API token. You don't need to send your API secret as the password. Make sure you never expose your API secret to on your client! It grants access to all other endpoints. ## Testing In the sandbox environment, you can simulate a successful ACH deposit using the account number `111111111` and routing number `120000003`.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Tokenizes a sensitive bank account details. ## Authentication When authenticating to this endpoint, you only need to send your API token. You don't need to send your API secret as the password. Make sure you never expose your API secret to on your client! It grants access to all other endpoints. ## Testing In the sandbox environment, you can simulate a successful ACH deposit using the account number `111111111` and routing number `120000003`.
{"__v":9,"_id":"569977887465970d00650be0","api":{"auth":"required","examples":{"codes":[]},"method":"get","params":[{"_id":"5699959d03721e0d0043a4c0","default":"","desc":"A token returned by the bank account tokenization endpoint.","name":"token","required":false,"type":"string","in":"path"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"token\": \"BTWiaGfEJovgG8JOwGOEnsz3\",\n  \"state\": \"customer_info_required\",\n  \"created_at\": 1452896917\n}","name":""},{"status":200,"language":"json","code":"{\n  \"token\": \"BT5A6ng2p9fVCpIJavDsgmim\",\n  \"state\": \"ready\",\n  \"created_at\": 1452898303\n}","name":""},{"status":404,"language":"json","code":"{\n  \"error\": \"no_such_bank_account\"\n}"}]},"settings":"","url":"/bank_accounts/:token"},"body":"You may want to check the status of bank account after you've generated it. This endpoint allows you to do just that.\n\n##Possible card states: \n[block:parameters]\n{\n  \"data\": {\n    \"0-1\": \"We require information about the customer before this bank account may be credited.\",\n    \"0-0\": \"`customer_info_required`\",\n    \"1-0\": \"`ready`\",\n    \"1-1\": \"The card is supported and may now be credited.\",\n    \"h-0\": \"State Name\",\n    \"h-1\": \"Description\"\n  },\n  \"cols\": 2,\n  \"rows\": 2\n}\n[/block]","category":"569972ac03721e0d0043a497","createdAt":"2016-01-15T22:49:44.119Z","editedParams":true,"editedParams2":true,"excerpt":"Retrieve information about the bank account token.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":2,"project":"53fba347e406d10c30ed5f61","slug":"retrieve-bank-account","sync_unique":"","title":"/bank_accounts/:token","type":"get","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

get/bank_accounts/:token

Retrieve information about the bank account token.

Path Params

token:
string
A token returned by the bank account tokenization endpoint.
You may want to check the status of bank account after you've generated it. This endpoint allows you to do just that. ##Possible card states: [block:parameters] { "data": { "0-1": "We require information about the customer before this bank account may be credited.", "0-0": "`customer_info_required`", "1-0": "`ready`", "1-1": "The card is supported and may now be credited.", "h-0": "State Name", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



You may want to check the status of bank account after you've generated it. This endpoint allows you to do just that. ##Possible card states: [block:parameters] { "data": { "0-1": "We require information about the customer before this bank account may be credited.", "0-0": "`customer_info_required`", "1-0": "`ready`", "1-1": "The card is supported and may now be credited.", "h-0": "State Name", "h-1": "Description" }, "cols": 2, "rows": 2 } [/block]
{"__v":1,"_id":"56997a2f54d7db17000eea54","api":{"auth":"required","examples":{"codes":[]},"method":"put","params":[{"_id":"569995ac3da4370d009d215e","default":"","desc":"A token returned by the bank account tokenization endpoint.","name":"token","required":false,"type":"string","in":"path"},{"_id":"56997a2f54d7db17000eea5a","required":false,"desc":"The customer's name if it differs from the name on the bank account.","default":"defaults to the name on the bank account","type":"string","name":"name","in":"body"},{"_id":"56997a2f54d7db17000eea59","required":false,"desc":"First line of the mailing address. Maximum 200 characters.","default":"","type":"string","name":"address_line1","in":"body"},{"_id":"56997a2f54d7db17000eea58","required":false,"desc":"Second line of the mailing address. Maximum 200 characters.","default":"optional","type":"string","name":"address_line2","in":"body"},{"_id":"56997a2f54d7db17000eea57","required":false,"desc":"The full name of the city. Maximum 100 characters.","default":"","type":"string","name":"address_city","in":"body"},{"_id":"56997a2f54d7db17000eea56","required":false,"desc":"The two character US state code. Must be all caps.","default":"","type":"string","name":"address_state","in":"body"},{"_id":"56997a2f54d7db17000eea55","required":false,"desc":"The 5 digit US postal code.","default":"","type":"string","name":"address_zip","in":"body"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"name\": \"John Smith\",\n  \"address_line1\": \"1 Stockton St.\",\n  \"address_line2\": null,\n  \"address_city\": \"San Francisco\",\n  \"address_state\": \"CA\",\n  \"address_zip\": \"94108\",\n  \"updated_at\": 1452898847\n}","name":""},{"status":400,"language":"json","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"address_line1 is missing\",\n    \"address_city is missing\",\n    \"address_state is missing\",\n    \"address_zip is missing\"\n  ]\n}","name":""}]},"settings":"","url":"/bank_accounts/:token/customer"},"body":"Before you can credit a bank account, you must provide additional information on the recipient. This is for our own compliance purposes.\n\nWe're required to collect:\n \n * The customer's full legal name if it's different from the name on the bank account.\n * The customer's address of residence.\n \nThis endpoint allows you to attach the customer's information to the bank account token from your back-end.","category":"569972ac03721e0d0043a497","createdAt":"2016-01-15T23:01:03.389Z","editedParams":true,"editedParams2":true,"excerpt":"Provide required customer information.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":3,"project":"53fba347e406d10c30ed5f61","slug":"bank-account-customer","sync_unique":"","title":"/bank_accounts/:token/customer","type":"put","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

put/bank_accounts/:token/customer

Provide required customer information.

Path Params

token:
string
A token returned by the bank account tokenization endpoint.

Body Params

name:
stringdefaults to the name on the bank account
The customer's name if it differs from the name on the bank account.
address_line1:
string
First line of the mailing address. Maximum 200 characters.
address_line2:
stringoptional
Second line of the mailing address. Maximum 200 characters.
address_city:
string
The full name of the city. Maximum 100 characters.
address_state:
string
The two character US state code. Must be all caps.
address_zip:
string
The 5 digit US postal code.
Before you can credit a bank account, you must provide additional information on the recipient. This is for our own compliance purposes. We're required to collect: * The customer's full legal name if it's different from the name on the bank account. * The customer's address of residence. This endpoint allows you to attach the customer's information to the bank account token from your back-end.

User Information

Try It Out

put
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Before you can credit a bank account, you must provide additional information on the recipient. This is for our own compliance purposes. We're required to collect: * The customer's full legal name if it's different from the name on the bank account. * The customer's address of residence. This endpoint allows you to attach the customer's information to the bank account token from your back-end.
{"__v":2,"_id":"56997cf5cb127f0d003cc18a","api":{"auth":"required","examples":{"codes":[]},"method":"post","params":[{"_id":"569995ba113a901900ef8fe4","default":"","desc":"A token returned by the bank account tokenization endpoint.","name":"token","required":false,"type":"string","in":"path"},{"_id":"56997d2ea1bc540d0058bca8","required":false,"desc":"The amount in _*cents*_.","default":"","type":"int","name":"amount","in":"body"},{"_id":"56997d2ea1bc540d0058bca7","required":false,"desc":"You may optionally specify your own reference_id. If specified, it must be unique for all payments made on your account. This can also be used to lookup transactions in case your connection to us times out. Must be 1 to 80 alphanumeric characters + underscores.","default":"optional","type":"string","name":"reference_id","in":"body"}],"results":{"codes":[{"name":"","code":"{\n  \"token\": \"BCMOhTXFXNdsigB\",\n  \"reference_id\": \"bJOApcaGSTFnDg7NdJjx\",\n  \"state\": \"pending\",\n  \"amount\": 100,\n  \"created_at\": 1452899597\n}","language":"json","status":201},{"status":400,"language":"json","code":"{\n  \"error\": \"validation_errors\",\n  \"validation_errors\": [\n    \"amount is missing\"\n  ]\n}"},{"status":400,"language":"json","code":"{\n  \"error\": \"duplicate_reference_id\"\n}"}]},"settings":"","url":"/bank_accounts/:token/credits"},"body":"Initiates an ACH credit to the specified bank account. The maximum value for an individual credit is $10,000.00.  ACH credits should post within 2-3 business days.","category":"569972ac03721e0d0043a497","createdAt":"2016-01-15T23:12:53.786Z","editedParams":true,"editedParams2":true,"excerpt":"Initiate an ACH credit to the card associated with the bank account token.","githubsync":"","hidden":false,"isReference":false,"link_external":false,"link_url":"","order":4,"project":"53fba347e406d10c30ed5f61","slug":"bank-account-credit","sync_unique":"","title":"/bank_accounts/:token/credits","type":"post","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

post/bank_accounts/:token/credits

Initiate an ACH credit to the card associated with the bank account token.

Path Params

token:
string
A token returned by the bank account tokenization endpoint.

Body Params

amount:
integer
The amount in _*cents*_.
reference_id:
stringoptional
You may optionally specify your own reference_id. If specified, it must be unique for all payments made on your account. This can also be used to lookup transactions in case your connection to us times out. Must be 1 to 80 alphanumeric characters + underscores.
Initiates an ACH credit to the specified bank account. The maximum value for an individual credit is $10,000.00. ACH credits should post within 2-3 business days.

User Information

Try It Out

post
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Result Format



Initiates an ACH credit to the specified bank account. The maximum value for an individual credit is $10,000.00. ACH credits should post within 2-3 business days.
{"__v":1,"_id":"56707b426995210d003aad71","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/payments?reference_id=my_transaction_id"},{"language":"ruby","code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Payment.search(reference_id: 'my_transaction_id')"}]},"method":"get","params":[{"_id":"56707b426995210d003aad73","required":false,"desc":"Search by a reference_id that you specified when creating the payment.","default":"optional","type":"string","name":"reference_id","in":"query"},{"_id":"56cc99e5f1ee861500685fc1","default":"optional","desc":"Search by payment state (i.e., `pending`, `scheduled`, `cleared`, `failed`).","name":"state","required":false,"type":"string","in":"query"},{"_id":"56707b426995210d003aad72","required":false,"desc":"The page number to return.","default":"defaults to 1","type":"int","name":"page","in":"query"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"page_count\": 1,\n  \"credits\": [\n    {\n      \"token\": \"CC2F1NivibprUxy\",\n      \"reference_id\": \"my_reference_id\",\n      \"state\": \"cleared\",\n      \"amount\": 100,\n      \"created_at\": 1450206654\n    }\n  ]\n}","name":"Payment found"},{"status":200,"language":"json","code":"{\n  \"page_count\": 0,\n  \"credits\": []\n}","name":"No payments found"}]},"settings":"","url":"/payments"},"body":"","category":"5699334d03721e0d0043a450","createdAt":"2015-12-15T20:42:42.902Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":0,"project":"53fba347e406d10c30ed5f61","slug":"payments-search","sync_unique":"","title":"/payments","type":"get","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

get/payments


Query Params

reference_id:
stringoptional
Search by a reference_id that you specified when creating the payment.
state:
stringoptional
Search by payment state (i.e., `pending`, `scheduled`, `cleared`, `failed`).
page:
integerdefaults to 1
The page number to return.

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



{"__v":9,"_id":"5528535adf965225000598ca","api":{"auth":"required","examples":{"codes":[{"language":"curl","code":"curl -X GET https://$API_TOKEN:$API_SECRET@sandbox.payout.com/v1/payments/CC3hXUSMgMpasvp"},{"language":"ruby","code":"require 'payout'\nPayout.api_url = ENV['PAYOUT_API_URL']\nPayout.api_token = ENV['PAYOUT_API_TOKEN']\nPayout.api_secret = ENV['PAYOUT_API_SECRET']\n\nPayout::Payment.retrieve('CC3hXUSMgMpasvp')"}]},"method":"get","params":[{"_id":"569995d8113a901900ef8fe5","required":false,"desc":"A token returned by either the card or bank account credit endpoints.","default":"","type":"string","name":"token","in":"path"}],"results":{"codes":[{"status":200,"language":"json","code":"{\n  \"token\": \"CCzkF66WBr5ZYIt\",\n  \"state\": \"cleared\",\n  \"amount\": 100,\n  \"created_at\": 1428706030\n}","name":"Cleared Card Credit"},{"status":200,"language":"json","code":"{\n  \"token\": \"BC0uUpcMc3DEJQE\",\n  \"reference_id\": \"QQilwHMj7R1RHAjpgvb5\",\n  \"state\": \"scheduled\",\n  \"amount\": 100,\n  \"created_at\": 1452899848\n}","name":"Scheduled Bank Credit"},{"name":"Failed Card Credit","status":200,"language":"json","code":"{\n  \"token\": \"CCnMn2lQtTGyVdP\",\n  \"state\": \"failed\",\n  \"error\": \"transaction_declined\",\n  \"amount\": 10000,\n  \"created_at\": 1452900333\n}"},{"status":404,"language":"json","code":"{\n  \"error\": \"no_such_payment\"\n}"}]},"settings":"","url":"/payments/:token"},"body":"Lookup a payment's status after submitting it.\n\n## Possible payment states:\n[block:parameters]\n{\n  \"data\": {\n    \"h-0\": \"State Name\",\n    \"h-1\": \"Description\",\n    \"0-0\": \"pending\",\n    \"2-0\": \"cleared\",\n    \"2-1\": \"The credit has completed and should be visible on the customer banking portal shortly (timing of visibility can depend on financial institution).\",\n    \"0-1\": \"We have received your payment request and will be submitting it to the appropriate financial institution shortly.\",\n    \"1-0\": \"scheduled\",\n    \"1-1\": \"The credit has been scheduled with the appropriate financial institution but has not yet cleared.\",\n    \"3-0\": \"failed\",\n    \"3-1\": \"An error occurred. Please see the `error` field.\"\n  },\n  \"cols\": 2,\n  \"rows\": 4\n}\n[/block]","category":"5699334d03721e0d0043a450","createdAt":"2015-04-10T22:48:58.993Z","editedParams":true,"editedParams2":true,"excerpt":"","githubsync":"","hidden":false,"link_external":false,"link_url":"","order":1,"project":"53fba347e406d10c30ed5f61","slug":"payment_lookup","sync_unique":"","title":"/payments/:token","type":"get","updates":[],"user":"5407b5f38d92a2be33a74bbc","version":"5452be95b7fa011600a75c4a","childrenPages":[]}

get/payments/:token


Path Params

token:
string
A token returned by either the card or bank account credit endpoints.
Lookup a payment's status after submitting it. ## Possible payment states: [block:parameters] { "data": { "h-0": "State Name", "h-1": "Description", "0-0": "pending", "2-0": "cleared", "2-1": "The credit has completed and should be visible on the customer banking portal shortly (timing of visibility can depend on financial institution).", "0-1": "We have received your payment request and will be submitting it to the appropriate financial institution shortly.", "1-0": "scheduled", "1-1": "The credit has been scheduled with the appropriate financial institution but has not yet cleared.", "3-0": "failed", "3-1": "An error occurred. Please see the `error` field." }, "cols": 2, "rows": 4 } [/block]

User Information

Try It Out

get
{{ tryResults.results }}
Method{{ tryResults.method }}
Request Headers
{{ tryResults.requestHeaders }}
URL{{ tryResults.url }}
Request Data
{{ tryResults.data }}
Status
Response Headers
{{ tryResults.responseHeaders }}

Definition

{{ api_url }}{{ page_api_url }}

Examples


Result Format



Lookup a payment's status after submitting it. ## Possible payment states: [block:parameters] { "data": { "h-0": "State Name", "h-1": "Description", "0-0": "pending", "2-0": "cleared", "2-1": "The credit has completed and should be visible on the customer banking portal shortly (timing of visibility can depend on financial institution).", "0-1": "We have received your payment request and will be submitting it to the appropriate financial institution shortly.", "1-0": "scheduled", "1-1": "The credit has been scheduled with the appropriate financial institution but has not yet cleared.", "3-0": "failed", "3-1": "An error occurred. Please see the `error` field." }, "cols": 2, "rows": 4 } [/block]