Create Payment

All CashAppPay API requests require authentication. The AuthorizationRequest and AuthorizationReply schemas are used for authorizing the Payment.

URI Summary

Action	URI Template	URI Example	Non-URI Request	Response
POST	/v[M.m]/stores/[StoreID]/payments/authorization/create/[TenderCode].[format]	/v1.0/stores/store123/payments/authorization/create/CA.json	JSON	200 + JSON response

Request Example

Copy this code sample.

{
  "createTimestamp": "2024-05-01T12:34:56Z",
  "orderInformation": {
    "orderId": "123456789"
  },
  "requestId": "a3-a19f-4e42-956d-d581ce135bec",
  "paymentMethod": {
    "cashAppPayData": {
      "grantId": "GRG_AZYyHv2viNAbIDn68CJTG0rApU4murQBTqtF4dzbwSHXCy13mvEV3byfaGHD5bgH8TKOktJpgI8gA"
    }
  },
  "amounts": {
    "total": {
      "currencyCode": "USD",
      "value": 10.95
    }
  },
  "billingInformation": {
    "address": {
      "line1": "935 First Ave",
      "city": "King of Prussia",
      "mainDivision": {
        "code": "PA"
      },
      "country": "US",
      "postalCode": "19406"
    },
    "contact": {
      "person": {
        "name": {
          "firstName": "John",
          "lastName": "Doe"
        }
      },
      "emailAddresses": [
        "demo@email.com"
      ],
      "phoneNumbers": [
        "9876543120"
      ]
    }
  },
  "shippingInformation": {
    "address": {
      "line1": "935 First Ave",
      "city": "King of Prussia",
      "mainDivision": {
        "code": "PA"
      },
      "country": "US",
      "postalCode": "19406"
    },
    "contact": {
      "person": {
        "name": {
          "firstName": "John",
          "lastName": "Doe"
        }
      },
      "emailAddresses": [
        "demo@email.com"
      ],
      "phoneNumbers": [
        "9876543120"
      ]
    }
  }
}

Request Elements

Element	Optional/Required	Description	Type	Restriction
createTimestamp	Required	Timestamp when the request is sent	String	dateTime
orderInformation	Required	Information about the order which is the unique identifier of an order.	ObjectType
orderInformation.orderId	Required	Unique identifier for an order.	String	Min 3 char Max 40 characters
requestId	Required	RequestId is used to uniquely identify a request. It is included to identify idempotent duplicate request processing. The value must be unique. It is recommended to use a variant UUID for the request ID. The same request ID should only be reused if a read timeout occurs when attempting to receive a response from the payment service. In all other cases a new request ID must be sent for retried requests, including responses such as Error, Timeout.	String	Min 3 characters Max 128 characters
paymentMethod	Required	Unique identifier of the payment transaction for the order.	ObjectType
paymentMethod.cashAppPayData	Required	Payment Information of the Cash App Pay order.	ObjectType
paymentMethod.cashAppPayData.grantId	Required	ID of Grant that is used to create a payment.	String	Min 4 characters
amounts	Required	Amount value and currency code of the order	ObjectType
amounts.total	Required	Total amount value and currency code of the order	ObjectType
amounts.total.currencyCode	Required	The currency of the order amount	ISO 4217 currency code
amounts.total.value	Required	Total value of the authorization.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
billingInformation	Required	Represents Billing Information of the order. Contains Customer Contact Information and Address.	ObjectType
billingInformation.address	Required	Represents customer billing address information.	ObjectType
billingInformation.address.line1	Required	The line1 components contain the street address.	String	Min 1 character Max 70 characters
billingInformation.address.city	Required	City of the Billing Address.	String	Min 1 character Max 40 characters
billingInformation.address.mainDivision	Required	Typically, a two- or three-digit postal abbreviation for the state or province.	ObjectType
billingInformation.address.mainDivision.code	Required	Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code.	String	Min 1 character Max 5 characters
billingInformation.address.country	Required	Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2	String
billingInformation.address.postalCode	Required	Postal code of the Billing Address.	String	Min 1 character Max 35 characters
billingInformation.contact	Required	Represents customer billing contact information.	ObjectType
billingInformation.contact.person	Required	Represents customer billing contact person information.	ObjectType
billingInformation.contact.person.name	Required	Represents customer billing contact person name information.	ObjectType
billingInformation.contact.person.name.firstName	Required	The first name of the customer placing the order.	String	Min 1 Character Max 64 characters
billingInformation.contact.person.name.lastName	Required	The last name of the customer placing the order.	String	Min 1 Character Max 64 characters
billingInformation.contact.emailAddresses	Required	Email address of the customer.	Array of String	Min 3 characters Max 150 characters
billingInformation.contact.phoneNumbers	Required	Customer phone number used for order follow-up.	Array of String	Min 10 characters Max 40 characters
shippingInformation	Required	Represents Shipping Information of the order. Contains Customer Contact Information and Address.	ObjectType
shippingInformation.address	Required	Represents customer shipping address information.	ObjectType
shippingInformation.address.line1	Required	The line1 components contain the street address.	String	Min 1 character Max 70 characters
shippingInformation.address.city	Required	City of the Shipping Address.	String	Min 1 character Max 40 characters
shippingInformation.address.mainDivision	Required	Typically, a two- or three-digit postal abbreviation for the state or province.	ObjectType
shippingInformation.address.mainDivision.code	Required	Typically, a two- or three-digit postal abbreviation for the state or province. This does not necessarily conform to the ISO 3166-2 code.	String	Min 1 character Max 5 characters
shippingInformation.address.country	Required	Two-digit ISO country code conforming to ISO 3166 alpha 2. See: http://en.wikipedia.org/wiki/ISO_3166-1_alpha-2	String
shippingInformation.address.postalCode	Required	Postal code of the Shipping Address.	String	Min 1 character Max 35 characters
shippingInformation.contact	Required	Represents customer shippingInformation contact information.	ObjectType
shippingInformation.contact.person	Required	Represents customer shippingInformation contact person information.	ObjectType
shippingInformation.contact.person.name	Required	Represents customer shippingInformation contact person name information.	ObjectType
shippingInformation.contact.person.name.firstName	Required	The first name of the customer placing the order.	String	Min 1 Character Max 64 characters
shippingInformation.contact.person.name.lastName	Required	The last name of the customer placing the order.	String	Min 1 Character Max 64 characters
shippingInformation.contact.emailAddresses	Required	Email address of the customer.	Array of String	Min 3 characters Max 150 characters
shippingInformation.contact.phoneNumbers	Required	Customer phone number used for order follow-up.	String	Min 10 characters Max 40 characters

Response Examples

Success Response

Http Status Code: 200

Copy this code sample.


{
  "success": true,
  "requestId": "a3-a19f-4e42-956d-d581ce135bec"
  "result": {
    "orderId": "123456789",
    "paymentMethod": {
      "tender": "CA",
      "accountIdentifier": {
        "identifier": "CASHAPPPAY",
        "token": true
      }
    },
    "responseCode": "APPROVED",
    "amountAuthorized": {
      "value": 10.95,
      "currencyCode": "USD"
    }
  }
}

Declined Response

Http Status Code: 200

Copy this code sample.

 {
  "success": false,
  "requestId": "a3-a19f-4e42-956d-d581ce135bec"
  "result": {
    "orderId": "123456789",
    "paymentMethod": {
      "tender": "CA",
      "accountIdentifier": {
        "identifier": "CASHAPPPAY",
        "token": true
      }
    },
    "responseCode": "DECLINED",
    "responseCodeDescription": "PAYMENT_PROCESSING_ERROR (PAYMENT_DECLINED_INSUFFICIENT_FUNDS): Payment could not be created. ",
    "amountAuthorized": {
      "value": 0,
      "currencyCode": "USD"
    }
  }
}

Error Response

Http Status Code: 200

Copy this code sample.

 {
  "success": false,
  "requestId": "a3-a19f-4e42-956d-d581ce135bec"
  "result": {
    "orderId": "123456789",
    "paymentMethod": {
      "tender": "CA",
      "accountIdentifier": {
        "identifier": "CASHAPPPAY",
        "token": true
      }
    },
    "responseCode": "ERROR",
    "responseCodeDescription": "GRANT_ERROR (GRANT_CONSUMED): This grant has already been consumed. grant_id",
    "amountAuthorized": {
      "value": 0,
      "currencyCode": "USD"
    }
  }
}

In case of an error response, the webstore should correct the request based on the response code and response code description, and retry the Authorization Request.

Timeout Response

Http Status Code: 500

Copy this code sample.

{
  "success": false,
  "requestId": "a3-a19f-4e42-956d-d581ce135bec"
  "errors": [
    {
      "systemId": "bb8eab7f-4474-4cc6-ae89-e7d61509961e",
      "code": "TIMEOUT",
      "message": "I/O error on POST request for \"https://sandbox.api.cash.app/network/v1/payments\":                         Connect to sandbox.api.cash.app:443 [sandbox.api.cash.app/151.101.46.133] failed: Connection refused;                         nested exception is org.apache.http.conn.HttpHostConnectException:                         Connect to sandbox.api.cash.app:443 [sandbox.api.cash.app/151.101.46.133] failed: Connection refused"
    }
  ]
}

In case of the timeout response, the webstore should retry the Authorization Request with same order id and a new request id.

If there is no response from Radial or the webstore could not get a response from Radial for any reason, the webstore should retry the Authorization Request with same order id and the same request id.

Response Elements

Element	Optional/Required	Description	Type	Restriction
success	Required	Attribute that indicates whether the authorization is success or not.	Boolean	true or false
requestId	Required	This is the same requestId that was sent in the request.	String	Min 3 characters Max 128 characters
result	Required	This contains details of the authorization result.	ObjectType
orderId	Required	Unique identifier for an order.	String	Min 3 characters Max 40 characters
paymentMethod	Required	Unique identifier of the payment transaction for the order.	ObjectType
paymentMethod.tender	Required	Identifies the tender. CA is the tender for Cash App Pay.	String	Only 2 characters
paymentMethod.accountIdentifier	Required	Contains identifier and token information.	ObjectType
paymentMethod.accountIdentifier.identifier	Required	CASHAPPPAY	String
paymentMethod.accountIdentifier.token	Required	Attribute that indicates whether the account identifier is tokenized.	Boolean	true or false
result.amountAuthorized	Required	Amount value and currency code of the order	ObjectType
result.amountAuthorized.value	Required	Total value of the authorization.	Decimal	Min 0.00 Max 9 digits Fraction 2 digits
result.amountAuthorized.currencyCode	Required	The currency of the order amount	ISO 4217 currency code
result.responseCode	Required	Used by client to determine APPROVED or DECLINED or ERROR response.	Enum	Can be any of these values: APPROVED DECLINED ERROR
result.responseCodeDescription	Optional	Reponse code description.	String
errors.systemId	Required	Radial generated unique identifier for the error.	String
errors.code	Required	Error code of the transaction.	Enum	TIMEOUT
errors.message	Required	Error code description.	String