Accepting local payments

How to support Braintree local payments

Problem

You want to allow your customers to checkout with the Braintree-supported local payment methods. You've properly configured your account in the Braintree control panel and integrated their client SDK. You now need to set up the payment source in order to support the different local payment workflows.

Solution

The first steps to setup local payments are similar to the standard ones, with the only notable difference you need to set the local attribute as true when you create the payment source.

pageAdding the payment source

After that, paths differ based on two possible scenarios — whether the customer is returning to your checkout or not.

Customers returning to your checkout

Assuming the customer goes back to your checkout application, you need to update the payment source with the payment_method_nonce returned by Braintree as with standard payments.

pageSending back the payment method nonce

Then you have just to update the order with the _place attribute in order to complete the payment.

pagePlacing the order

Upon successful response by Braintree, the order will be captured and approved automatically, since the transaction is already settled by the local payment gateway chosen by the customer.

Customers leaving your site after payment

If the customer doesn't return to your checkout application, you need to follow a slightly different workflow:

Configure Braintree webhooks to notify Commerce Layer about the payment results — to do that, use the webhook_endpoint_url exposed by the Braintree gateway resource.
Update it with the payment_id returned by the client SDK, in order to let our webhook find and update the payment source used for the payment.
Monitor the order's status, since our webhook will update the payment source with the payment_method_nonce, place the order, and — upon successful response by Braintree — capture and approve it in a single step.

Example

1. Create the local payment source

The following request creates a Braintree payment object and associates it with the order identified by the "qaMAhZkZvd" ID:

curl -g -X POST \
  'http://yourdomain.commercelayer.io/api/braintree_payments' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "braintree_payments",
    "attributes": {
      "local": true
    },
    "relationships": {
      "order": {
        "data": {
          "type": "orders",
          "id": "qaMAhZkZvd"
        }
      }
    }
  }
}'

On success, the API responds with a 201 Created status code, returning the created Braintree payment object:

{
  "data": {
    "id": "vdDEAsZYzR",
    "type": "braintree_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR"
    },
    "attributes": {
      "client_token": "xxxx.yyyy.zzzz",
      "payment_method_nonce": null,
      "payment_id": null,
      "local": true,
      "options": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}

2. Update the payment source with the payment ID

The following request updates the Braintree payment source identified by the "vdDEAsZYzR" ID with the payment_id received from the client:

curl -g -X PATCH \
  'http://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR' \
  -H 'Accept: application/vnd.api+json' \
  -H 'Authorization: Bearer your-access-token' \
  -H 'Content-Type: application/vnd.api+json' \
  -d '{
  "data": {
    "type": "braintree_payments",
    "id": "vdDEAsZYzR",
    "attributes": {
      "payment_id": "xxxx.yyyy.zzzz"
    }
  }
}'

On success, the API responds with a 200 OK status code, returning the updated Braintree payment object:

{
  "data": {
    "id": "vdDEAsZYzR",
    "type": "braintree_payments",
    "links": {
      "self": "https://yourdomain.commercelayer.io/api/braintree_payments/vdDEAsZYzR"
    },
    "attributes": {
      "client_token": "xxxx.yyyy.zzzz",
      "payment_method_nonce": null,
      "payment_id": "xxxx.yyyy.zzzz",
      "local": true,
      "options": {},
      "payment_instrument":{...},
      "created_at": "2018-01-01T12:00:00.000Z",
      "updated_at": "2018-01-01T12:00:00.000Z",
      "reference": null,
      "reference_origin": null,
      "metadata": {}
    },
    "relationships": {
      "order": {
        "links": {...}
      }
    },
    "meta": {
      "mode": "test"
    }
  }
}