Braintree
Braintree#
About Braintree#
DISCLAIMER: Please read the docs available at braintree to know how braintree works and how its APIs are intended to work.
Braintree provides good docs to make you knowledgeable about what are important fields and what fields can be left from the API requests.
This doc just provides examples as what is possible with the API but you should consult braintree and their API documentation before using kazoo's braintree modules.
Test out braintree using sandbox account before deploying it in production as the module is considered NOT PRODUCTION READY.
Schema#
Fetch#
GET /v2/accounts/{ACCOUNT_ID}/braintree/client_token
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/client_token
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"client_token": "{BRAINTREE_CLIENT_TOKEN}"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Show this account's credits#
GET /v2/accounts/{ACCOUNT_ID}/braintree/credits
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/credits
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"amount": 500.0,
"billing_account_id": "31a05ddba6a9df166c7d50fc4b683606"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Add credit to this account#
PUT /v2/accounts/{ACCOUNT_ID}/braintree/credits
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"amount":200.00}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/credits
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"bookkeeper_info": {
"add_ons": [],
"amount": "20.00",
"avs_postal_response": "M",
"avs_street_response": "I",
"card": {
"bin": "411111",
"card_type": "Visa",
"customer_location": "US",
"default": false,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"id": "7gz3qw",
"last_four": "1111"
},
"ccv_response_code": "I",
"created_at": "2016-09-29T14:22:54Z",
"currency_code": "USD",
"customer": {
"company": "ACME Corp",
"first_name": "John",
"id": "31a05ddba6a9df166c7d50fc4b657854",
"last_name": "Doe",
"phone": "9122475533"
},
"discounts": [],
"id": "0gmy6jrw",
"is_api": true,
"is_automatic": false,
"is_recurring": false,
"merchant_account_id": "romanat",
"order_id": "a6268d1a31a76d53857fae0d",
"processor_authorization_code": "XJ3YL9",
"processor_response_code": "1000",
"processor_response_text": "Approved",
"purchase_order": "3001",
"status": "submitted_for_settlement",
"tax_exempt": false,
"type": "sale",
"update_at": "2016-09-29T14:22:54Z"
},
"description": "credit addition from credit card",
"id": "80591de5690374ebba7adc4ffaaf51c1",
"order_id": "a6268d1a31a76d53857fae0d310552ab",
"sub_account_id": "22f1b082e505064cc930e944bf9a0728",
"sub_account_name": "romana"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
List this account's transactions#
GET /v2/accounts/{ACCOUNT_ID}/braintree/transactions
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/transactions
{
"auth_token": "{AUTH_TOKEN}",
"data": [{
"id": "{TRANSACTION_ID}",
"status": "{STATUS_OF_TRANSACTION}",
"type": "sale",
"currency_code": "{CURRENCY_CODE}",
"amount": "20.00",
"merchant_account_id": "{BRAINTREE_MERCHANT_ID}",
"order_id": "{ORDER_ID}",
"purchase_order": "3001",
"created_at": "2016-09-29T14:22:54Z",
"update_at": "2016-09-29T14:22:54Z",
"avs_postal_response": "M",
"avs_street_response": "I",
"ccv_response_code": "I",
"processor_authorization_code": "XJ3LR9",
"processor_response_code": "1000",
"processor_response_text": "Approved",
"tax_exempt": false,
"billing_address": {
{BRAINTREE_CUSTOMER_ADDRESS}
},
"shipping_address": {
{BRAINTREE_CUSTOMER_SHIPPING_ADDRESS}
},
"customer": {
{BRAINTREE_CUSTOMER_INFO}
},
"card": {
{BRAINTREE_CREDIT_CARD_DETAILS}
},
"add_ons": [
{ADDONS_IN_ORDER}
],
"discounts": [
{DISCOUNTS_APPLIED_TO_ORDER}
],
"is_api": true,
"is_automatic": {AUTOMATIC_BILLING},
"is_recurring": {RECURRING_SUBSCRIPTION}
}],
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
List addresses#
GET /v2/accounts/{ACCOUNT_ID}/braintree/addresses
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/addresses
{
"auth_token": "{AUTH_TOKEN}",
"data": [
{
"company": "{CUSTOMER_COMPANY}",
"country_code": "{BRAINTREE_COUNTRY_CODE}",
"country_code_three": "{BRAINTREE_COUNTRY_CODE_THREE}",
"country_code_two": "{BRAINTREE_COUNTRY_CODE_TWO}",
"country_name": "{BRAINTREE_COUNTRY_NAME}",
"created_at": "2016-09-23T00:20:51Z",
"customer_id": "{ACCOUNT_ID}",
"extended_address": "{EXTENDED_CUSTOMER_ADDRESS}",
"first_name": "{CUSTOMER_FIRST_NAME}",
"id": "7x",
"last_name": "{CUSTOMER_LAST_NAME}",
"locality": "{CUSTOMER_LOCALITY}",
"postal_code": "{CUSTOMER_POSTAL_CODE}",
"region": "{BRAINTREE_REGION}",
"street_address": "{CUSTOMER_ADDRESS}",
"updated_at": "2016-09-23T00:20:51Z"
}
],
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Add an address#
PUT /v2/accounts/{ACCOUNT_ID}/braintree/addresses
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"{ADDRESS_INFORMATION}"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/addresses
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"company": "{CUSTOMER_COMPANY}",
"country_code": "{BRAINTREE_COUNTRY_CODE}",
"country_code_three": "{BRAINTREE_COUNTRY_CODE_THREE}",
"country_code_two": "{BRAINTREE_COUNTRY_CODE_TWO}",
"country_name": "{BRAINTREE_COUNTRY_NAME}",
"created_at": "2016-09-23T00:20:51Z",
"customer_id": "{ACCOUNT_ID}",
"extended_address": "{EXTENDED_CUSTOMER_ADDRESS}",
"first_name": "{CUSTOMER_FIRST_NAME}",
"id": "7x",
"last_name": "{CUSTOMER_LAST_NAME}",
"locality": "{CUSTOMER_LOCALITY}",
"postal_code": "{CUSTOMER_POSTAL_CODE}",
"region": "{BRAINTREE_REGION}",
"street_address": "{CUSTOMER_ADDRESS}",
"updated_at": "2016-09-23T00:20:51Z"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
List credit cards#
GET /v2/accounts/{ACCOUNT_ID}/braintree/cards
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards
{
"auth_token": "{AUTH_TOKEN}",
"data": [{
"id": "{CARD_ID}",
"bin": "{CARD_FIRST_SIX_DIGITS}",
"card_type": "Visa",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"default": true,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"customer_location": "US",
"last_four": "1111",
"customer_id": "{ACCOUNT_ID}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"billing_address": {
{BRAINTREE_ADDRESS}
},
"billing_address_id": "{BRAINTREE_ADDRESS_ID}"
}],
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Add a credit card#
PUT /v2/accounts/{ACCOUNT_ID}/braintree/cards
To add a credit card, the information about a credit card can be sent in the request or payment_token_nonce
.
with payment method nonce#
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"payment_method_nonce":"valid-nonce"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{CARD_ID}",
"bin": "{CARD_FIRST_SIX_DIGITS}",
"card_type": "Visa",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"default": true,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"customer_location": "US",
"last_four": "1111",
"customer_id": "{ACCOUNT_ID}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"billing_address": {
{BRAINTREE_ADDRESS}
},
"billing_address_id": "{BRAINTREE_ADDRESS_ID}"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
with credit card info#
curl -v -X PUT \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"{CREDIT_CARD_INFO}"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{CARD_ID}",
"bin": "{CARD_FIRST_SIX_DIGITS}",
"card_type": "Visa",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"default": true,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"customer_location": "US",
"last_four": "1111",
"customer_id": "{ACCOUNT_ID}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"billing_address": {
{BRAINTREE_ADDRESS}
},
"billing_address_id": "{BRAINTREE_ADDRESS_ID}"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Get this account's details#
GET /v2/accounts/{ACCOUNT_ID}/braintree/customer
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/customer
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{ACCOUNT_ID}",
"first_name": "John",
"last_name": "Doe",
"company": "Presentation",
"phone": "9122475533",
"created_at": "2016-09-17T21:08:01Z",
"updated_at": "2016-09-23T00:20:53Z",
"credit_cards": [{
{BRAINTREE_CREDIT_CARD}
}],
"addresses": [{
{BRAINTREE_CUSTOMER_ADDRESS}
}]
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Add a customer#
POST /v2/accounts/{ACCOUNT_ID}/braintree/customer
To add a customer we can send the customer's info as with just customer's name, company and phone or can add a payment_method_nonce
with it,
or add a credit card with the customer info with card's info or with payment_method_nonce
token.
the user can be added without any credit card#
{
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "ACME CORP",
"phone": "6000000000"
}
}
without any credit card and contains payment method nonce in their json request#
{
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "ACME CORP",
"phone": "6000000000",
"payment_method_nonce": "valid-nonce"
}
}
payment method nonce is added to the credit card section#
{
"data": {
"first_name": "John",
"last_name": "Doe",
"company": "ACME CORP",
"phone": "6000000000",
"credit_card":{
"payment_method_nonce": "valid-nonce"
}
}
}
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"{CUSTOMER_INFO}"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/customer
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{ACCOUNT_ID}",
"first_name": "John",
"last_name": "Doe",
"company": "Presentation",
"phone": "9122475533",
"created_at": "2016-09-17T21:08:01Z",
"updated_at": "2016-09-23T00:20:53Z",
"credit_cards": [{
{BRAINTREE_CREDIT_CARD}
}],
"addresses": [{
{BRAINTREE_CUSTOMER_ADDRESS}
}]
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Fetch details on a transaction#
GET /v2/accounts/{ACCOUNT_ID}/braintree/transactions/{TRANSACTION_ID}
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/transactions/{TRANSACTION_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{TRANSACTION_ID}",
"status": "{STATUS_OF_TRANSACTION}",
"type": "sale",
"currency_code": "{CURRENCY_CODE}",
"amount": "20.00",
"merchant_account_id": "{BRAINTREE_MERCHANT_ID}",
"order_id": "{ORDER_ID}",
"purchase_order": "3001",
"created_at": "2016-09-29T14:22:54Z",
"update_at": "2016-09-29T14:22:54Z",
"avs_postal_response": "M",
"avs_street_response": "I",
"ccv_response_code": "I",
"processor_authorization_code": "XJ3LR9",
"processor_response_code": "1000",
"processor_response_text": "Approved",
"tax_exempt": false,
"billing_address": {
{BRAINTREE_CUSTOMER_ADDRESS}
},
"shipping_address": {
{BRAINTREE_CUSTOMER_SHIPPING_ADDRESS}
},
"customer": {
{BRAINTREE_CUSTOMER_INFO}
},
"card": {
{BRAINTREE_CREDIT_CARD_DETAILS}
},
"add_ons": [
{ADDONS_IN_ORDER}
],
"discounts": [
{DISCOUNTS_APPLIED_TO_ORDER}
],
"is_api": true,
"is_automatic": {AUTOMATIC_BILLING},
"is_recurring": {RECURRING_SUBSCRIPTION}
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Remove an address#
DELETE /v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Fetch an address' details#
GET /v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "7x",
"customer_id": "{ACCOUNT_ID}",
"first_name": "{CUSTOMER_FIRST_NAME}",
"last_name": "{CUSTOMER_LAST_NAME}",
"company": "{CUSTOMER_COMPANY}",
"street_address": "{CUSTOMER_ADDRESS}",
"extended_address": "{EXTENDED_CUSTOMER_ADDRESS}",
"locality": "{CUSTOMER_LOCALITY}",
"region": "{BRAINTREE_REGION}",
"postal_code": "{CUSTOMER_POSTAL_CODE}",
"country_code": "{BRAINTREE_COUNTRY_CODE}",
"country_code_two": "{BRAINTREE_COUNTRY_CODE_TWO}",
"country_code_three": "{BRAINTREE_COUNTRY_CODE_THREE}",
"country_name": "{BRAINTREE_COUNTRY_NAME}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-23T00:20:51Z"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Update an address#
POST /v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
curl -v -X POST \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"{ADDRESS_INFORMATION}"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/addresses/{ADDRESS_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "7x",
"customer_id": "{ACCOUNT_ID}",
"first_name": "{CUSTOMER_FIRST_NAME}",
"last_name": "{CUSTOMER_LAST_NAME}",
"company": "{CUSTOMER_COMPANY}",
"street_address": "{CUSTOMER_ADDRESS}",
"extended_address": "{EXTENDED_CUSTOMER_ADDRESS}",
"locality": "{CUSTOMER_LOCALITY}",
"region": "{BRAINTREE_REGION}",
"postal_code": "{CUSTOMER_POSTAL_CODE}",
"country_code": "{BRAINTREE_COUNTRY_CODE}",
"country_code_two": "{BRAINTREE_COUNTRY_CODE_TWO}",
"country_code_three": "{BRAINTREE_COUNTRY_CODE_THREE}",
"country_name": "{BRAINTREE_COUNTRY_NAME}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-23T00:20:51Z"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Remove a credit card#
DELETE /v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
curl -v -X DELETE \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": { },
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Fetch a credit card's details#
GET /v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
curl -v -X GET \
-H "X-Auth-Token: {AUTH_TOKEN}" \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{CARD_ID}",
"bin": "{CARD_FIRST_SIX_DIGITS}",
"card_type": "Visa",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"default": true,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"customer_location": "US",
"last_four": "1111",
"customer_id": "{ACCOUNT_ID}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"billing_address": {
{BRAINTREE_ADDRESS}
},
"billing_address_id": "{BRAINTREE_ADDRESS_ID}"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}
Update a credit card#
POST /v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
curl -v -X POST \
-H "X-Auth-Token: {AUTH_TOKEN}" \
-H "Content-Type: application/json" \
-d '{"data":{"{CREDIT_CARD_INFO_OR_PAYMENT_NONCE}"}}' \
http://{SERVER}:8000/v2/accounts/{ACCOUNT_ID}/braintree/cards/{CARD_ID}
{
"auth_token": "{AUTH_TOKEN}",
"data": {
"id": "{CARD_ID}",
"bin": "{CARD_FIRST_SIX_DIGITS}",
"card_type": "Visa",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"default": true,
"expiration_month": "11",
"expiration_year": "2020",
"expired": false,
"customer_location": "US",
"last_four": "1111",
"customer_id": "{ACCOUNT_ID}",
"created_at": "2016-09-23T00:20:51Z",
"updated_at": "2016-09-29T14:22:54Z",
"billing_address": {
{BRAINTREE_ADDRESS}
},
"billing_address_id": "{BRAINTREE_ADDRESS_ID}"
},
"request_id": "{REQUEST_ID}",
"revision": "{REVISION}",
"status": "success"
}