Braintree Grant Customer Token

Tokenizing granted nonces for use with Braintree payments

Create a Braintree grant customer token

Here is an example of a successful request for a Braintree grant tokenization to accept USD payment in the US.

Create customer token using a Braintree grant (nonce)

POST https://staging.api.xpay.xcover.com/customer-tokens/braintree-grant

Headers

Name	Type	Description
Authorization*	String	Bearer {{JWT}}

201: Created Grant/nonce successfully tokenized

422: Unprocessable Entity Problem tokenizing grant/nonce

Request

{
    "country": "US",
    "currency": "USD",
    "underwriter": "Asservo",
    "customer": {
      "email": "[email protected]"
    },
    "nonce": "fake-valid-no-billing-address-nonce"
}

Response

HTTP 201

{
    "data": {
        "id": "d523a6fd-b712-4c3d-827f-88f0108a07f0",
        "customerId": "e7860c44-8f8b-42a9-b373-8d15e3675517",
        "paymentProviderId": "6536085a-05e8-49b0-b34a-c3c0ff76333b",
        "createdAt": "2022-10-14T02:50:53+00:00",
        "updatedAt": "2022-10-14T02:50:53+00:00",
        "metadata": {
            "paymentMethod": "Braintree Grant",
            "expiry": "2022-10-14T05:50:53.919874Z"
        },
        "partnerId": null,
        "isVisible": true,
        "isDefault": true,
        "isParentMultiToken": false,
        "createdBy": "6ea750c6-fbdb-30ec-9b85-d2e3a001152c",
        "security": null
    }
}

Create customer token using a Braintree Shared Vault

POST https://staging.api.xpay.xcover.com/customer-tokens/braintree-grant

Headers

Name	Type	Description
Authorization*	String	Bearer {{JWT}}

201: Created Grant/nonce successfully tokenized

422: Unprocessable Entity Problem tokenizing grant/nonce

Request

{
    "country": "US",
    "currency": "USD",
    "customer": {
      "email": "[email protected]"
    },
    "shared_vault_token": "abc123"
}

Response

HTTP 201

{
    "data": {
        "id": "d523a6fd-b712-4c3d-827f-88f0108a07f0",
        "customerId": "e7860c44-8f8b-42a9-b373-8d15e3675517",
        "paymentProviderId": "6536085a-05e8-49b0-b34a-c3c0ff76333b",
        "createdAt": "2022-10-14T02:50:53+00:00",
        "updatedAt": "2022-10-14T02:50:53+00:00",
        "metadata": {
            "paymentMethod": "Braintree Grant",
            "paymentType": "Apple Pay - Visa"
        },
        "partnerId": null,
        "isVisible": true,
        "isDefault": true,
        "isParentMultiToken": false,
        "createdBy": "6ea750c6-fbdb-30ec-9b85-d2e3a001152c",
        "security": null
    }
}

Failure Scenarios

There are several reasons why a tokenization of a nonce may fail. Here are some examples.

Invalid or expired nonce

Request

{
  "country": "US",
  "currency": "USD",
  "customer": {
  	"email": "[email protected]"
  },
  "nonce": "invalid-nonce"
}

Response

HTTP 422

{
    "type": "exception",
    "message": "Braintree update request failed: Unknown or expired payment_method_nonce."
}

Missing or invalid customer data

Request

{
  "country": "US",
  "currency": "USD",
  "customer": {
  	"email": ""
  },
  "nonce": "fake-valid-no-billing-address-nonce"
}

Response

HTTP 422

{
    "type": "exception",
    "message": "The given data was invalid.",
    "errors": {
        "customer.id": [
            "The customer.id field is required when none of customer.identifier / customer.email are present."
        ],
        "customer.email": [
            "The customer.email field is required when none of customer.identifier / customer.id are present."
        ],
        "customer.identifier": [
            "The customer.identifier field is required when none of customer.email / customer.id are present."
        ]
    },

Invalid underwriter / currency / country combination

Request

{
  "country": "US",
  "currency": "GBP",
  "underwriter": "Non-existent Underwriter",
  "customer": {
  	"email": "[email protected]"
  },
  "nonce": "fake-valid-no-billing-address-nonce"
}

Response

HTTP 400

{
    "type": "exception",
    "message": "Could not find suitable PaymentProviderMethod for country/currency combination"
}