Technical Reference

Pay

Pay Kit initializes to window.CashApp when you include our script and exposes an asynchronous pay method which requires a Client ID. The Promise resolves an instance of Pay.

1
<script src="https://kit.cash.app/v1/pay.js"></script>
2
<script>
3
  const pay = await window.CashApp.pay({ clientId: 'YOUR_CLIENT_ID');
4
</script>

Parameters

addEventListener

Pay exposes an addEventListener method that listens for events throughout the lifecycle of paying.

1
pay.addEventListener('CUSTOMER_REQUEST_APPROVED', (data) => {});

Parameters

PayEventListener: (data: PayEventData) => void

The "CUSTOMER_REQUEST_DECLINED" and "CUSTOMER_REQUEST_FAILED" events will not receive data.

PayEventData: CustomerInteractionData | CustomerRequestData

CustomerInteractionData

CustomerRequestData

Customer

The Customer who approved the request.

Grants

The map of action to details about a grant may have keys payment or onFile (same as Actions below). GrantDetail has the following properties:

Returns

void

removeEventListener

Pay exposes a removeEventListener method that removes an event listener previously registered with addEventListener.

1
const createPayment = ({ grants }) => {
2
  // create your payment with the grant
3
};
4
5
pay.addEventListener('CUSTOMER_REQUEST_APPROVED', createPayment);
6
7
// when your application needs to destroy, teardown, unmount, etc.
8
pay.removeEventListener('CUSTOMER_REQUEST_APPROVED', createPayment);

Parameters

Returns

void

customerRequest

Pay exposes a customerRequest method that creates a Customer Request with one or more actions. You’ll need a Merchant to create a payment.

1
await pay.customerRequest({
2
  actions: {
3
    payment: {
4
      amount: {
5
        currency: 'USD',
6
        value: 1234, // $12.34
7
      },
8
      scopeId: 'merchant_id_from_network_api',
9
    },
10
  },
11
  redirectURL: window.location.href, // where mobile customers should be redirected to
12
  referenceId: 'your_reference_id', // perhaps a cart or checkout identifier
13
});

Parameters

The customerRequest method takes a CustomerRequestDetails object as its only argument. It has the following properties:

Actions is an object with optional onFile and payment properties, but at least one must exist.

onFile

payment

Amount

Amount to charge the customer.

Returns

Promise<CustomerRequestController>

CustomerRequestController

CustomerRequestController controls the Customer Request.

1
const details = { referenceId: 'initial', redirectURL: '...', actions: { ... } };
2
const { update } = await pay.customerRequest(details)
3
4
details.referenceId = 'final'
5
6
const success = await update(details)
7
if (success) {
8
  // continue creating payment with latest details
9
} else {
10
  // creating payment could possibly fail if a more complex change was made to `details`
11
}

update

The update method will update your Customer Request. The same validation applies (for example, must have at least one action) except redirectURL cannot be changed.

Returns Promise<boolean> to indicate if the update was successful. An example of when an update would not be successful is if the Customer Request has already been approved.

render

Pay exposes a render method that renders a managed Cash App Pay UI into your DOM.

1
await pay.render('#cash-app-pay');

Parameters

RenderOptions is an object with these optional properties:

ButtonOptions is an object with these optional properties:

Returns

Promise<RenderController>

RenderController

RenderController can control rendering.

begin

The begin method will begin the authorization flow for the customer if the manage option was false. Otherwise, it is a no-op. To use your own button and control the flow, you must set both manage and button to false.

1
const { begin } = await pay.render('#cash-app-pay', {
2
  button: false,
3
  manage: false,
4
});
5
6
document.querySelector('#my-checkout-button').addEventListener('click', () => {
7
  // NB: a customer may be redirected away from your page
8
  begin();
9
});

destroy

The destroy method will remove the Cash App Pay UI from your DOM.

1
const { destroy } = await pay.render('#cash-app-pay');
2
3
// when your application needs to teardown, unmount, etc.
4
destroy();

restart

Pay exposes a restart method that removes all rendered UI as well as the current customer request.

In a single page app,pay.restart() must be called whenever the buyer leaves the checkout page. You can only make a new customer request after restart, if the current customer request is approved.

1
await pay.restart();

Parameters

None

Returns

void

Custom elements

Pay Kit provides custom elements to help customize checkout experiences while making it easy to follow brand guidelines.

Logo

The <cash-app-pay-logo> element renders the Cash App Pay logo and can be customized with two attributes:

Customer

The <cash-app-pay-customer> element renders the Cash App Pay logo and a customer’s $Cashtag. The cashtag attribute is required and will be automatically truncated if needed. The element will grow to fill its parent container.

1
<cash-app-pay-customer cashtag="$jack" />