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
{
  "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

{
  "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
 {
  "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
 {
  "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
{
    "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