Local Payment Methods

Server-Side Implementationanchor

note

Ruby 2.104.1 or higher is required to use Local Payment Methods.

important

Vaulting payment methods and creating recurring transactions are currently not supported with Local Payment Methods.

Local Payment Method webhooksanchor

Local Payment Methods involve customers leaving your checkout flow to approve the payment through an app, their website, or directly with their bank. After completing the payment, the customer returns to your checkout flow to finish making their purchase. It's possible for a customer to not return to your app or website after successfully completing the payment with their bank. When this happens, the bank transaction will have processed even if the customer did not finish making their purchase through your checkout flow. In a case like this, you have two options:

  • If you can complete your checkout flow without the customer returning to your app or website, then use Local Payment Method webhooks to create the transaction and charge the customer.

  • If you need the customer to return to your app or website to complete your checkout flow, then inform the customer to do so. If they don't, and you are unable to create the transaction within 3 hours of invoking the checkout flow, Braintree will auto-refund the money to the customer.

  • If a transaction was not created, Braintree will initiate the refund of the money to the customer and will send you the local_payment_reversed webhook. You can use this webhook to notify your buyer that their funds will be returned and to expect them within 2-3 days.

Configure webhooksanchor

Webhooks are critical to the success of integrating with Local Payment Methods. Webhooks allow you to handle a case where a buyer approves the payment with their bank and chooses to not return to your app or website. See the webhooks guide for a general overview on how to configure webhooks.

Below is an example of a Local Payment Method completed webhook:

  1. JSON
{
  "local_payment": {
    "payment_id": "the_payment_id",
    "payment_method_nonce": "nonce_from_the_webhook",
  }
}
note

Braintree recommends that you store the payment_id returned to your client when starting the payment, and map it to a shopping cart identifier or some other form of identifier. When this webhook is received by your server, you can then look up the pending order using the included payment_id.

See the Local Payment Method webhooks reference for details on the exact content of the Local Payment Method completed notification.

Creating transactionsanchor

There are two ways to create a local payment transaction; in both cases, your server will receive a payment_method_nonce that can be used to create the transaction. To successfully integrate with Local Payment Methods, you must support both of these methods:

  1. If the customer does return to your app or website after completing the payment with their bank, then you must create the transaction using the payment_method_nonce sent to your server by your client.
  2. If the customer does not return to your app or website after completing the payment with their bank, then you must create the transaction using the payment_method_nonce contained in the Local Payment Method webhook sent to your server.

Once your server receives a payment_method_nonce, include the payment_method_nonce parameter in the Transaction: Sale call on your server. Because Local Payment Methods only support single-use, one-time payments, submit_for_settlement must be set to true.

Optional fieldsanchor

  • order_id - a merchant-generated ID associated with the transaction
  • descriptor_name - a descriptor that will show in the user's bank statement

Below includes an example call with relevant parameters:

  1. Ruby
result = gateway.transaction.sale(
  :amount => "10.00",
  :payment_method_nonce => nonce_from_the_client_or_webhook,
  :order_id => "Order 1234",
  :descriptor_name => "Merchant ABC",
  :options => {
    :submit_for_settlement => true, # Required
  }
)
if result.success?
  "Success ID: #{result.transaction.id}"
else
  result.message
end
note

Attempting to call Transaction.sale twice for the same Local Payment Method (using a nonce from the client and a nonce from the webhook) will result in a validation error.

Currency supportanchor

The currency of transactions for use with Local Payment Methods needs to match the currency set in the client integration.

Payment Contextsanchor

When a customer clicks the Local Payment Method button, Braintree tracks this interaction by using a Payment Context. Once the customer has approved the payment with their bank through their website or wallet app, Braintree will then update the Payment Context and send you a webhook. If the customer does not approve the payment, the Payment Context will eventually be marked expired.

note

Payment Context Graphql API can also be used as an alternative to webhooks. See Payment Context API example.


Next Page: Testing and Go Live →