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
{
"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
{
"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
{
"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
{
"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
{
"success": false,
"requestId": "526ae2b0-c763-5046-b012-9655a0e9bc9a",
"errors": [
{
"systemId": "0f33d3e9-2140-40d5-9cf8-1c57290730b6",
"code": "TIMEOUT",
"message": "Timeout From Gateway"
}
]
}
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 |