openapi: 3.2.0 info: title: Cash App Grants API version: 1.0.0 description: 'Operations tagged Grants across 2 of this provider''s published API definitions: cash-app-grants-afterpay-openapi.json, cash-app-grants-cash-app-pay-openapi.json. Each path carries the servers of the definition it was published in.' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production tags: - name: Grants paths: /v2/grants/approvals: post: operationId: start-grant-approval summary: Create Grant Approval description: Initiates the approval process for a new grant. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: Accept in: header required: false schema: type: string default: application/json responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GrantApprovalResponse' '401': description: 'Authentication failed or insufficient permissions. | errorCode | Description | | --- | --- | | unauthorized | The API credentials are invalid or missing. | | insufficient_permissions | The merchant lacks the required ''merchant_api_v2/initiate'' permission. | ' content: application/json: schema: description: Any type '403': description: '| errorCode | Description | | --- | --- | | feature_not_enabled | On file payments are not enabled for this merchant. | ' content: application/json: schema: description: Any type '415': description: Unsupported Media Type - Content-Type header is missing or invalid content: application/json: schema: description: Any type '422': description: '| errorCode | Description | | --- | --- | | invalid_object | One or more required fields in the request body were missing or invalid. | ' content: application/json: schema: description: Any type requestBody: content: application/json: schema: $ref: '#/components/schemas/GrantApprovalRequest' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants: post: operationId: create-grant summary: Create Grant description: Creates a new grant from a grant approval token. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: Accept in: header required: false schema: type: string default: application/json responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/GrantResponse' '403': description: '| errorCode | Description | | --- | --- | | feature_not_enabled | On file payments are not enabled for this merchant. | ' content: application/json: schema: description: Any type '412': description: '| errorCode | Description | | --- | --- | | consumer_ineligible | Consumer not eligible | ' content: application/json: schema: description: Any type '415': description: Unsupported Media Type - Content-Type header is missing or invalid content: application/json: schema: description: Any type requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateGrantRequest' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/{grantId}: get: operationId: get-grant summary: Retrieve Grant description: Retrieves a grant by its ID. tags: - Grants parameters: - name: grantId in: path description: ID of the grant to retrieve. required: true schema: type: string - name: Authorization in: header description: Basic authentication required: true schema: type: string responses: '200': description: Created content: application/json: schema: $ref: '#/components/schemas/GrantResponse' '403': description: '| errorCode | Description | | --- | --- | | feature_not_enabled | On file payments are not enabled for this merchant. | ' content: application/json: schema: description: Any type '404': description: '| errorCode | Description | | --- | --- | | grant_not_found | The specified grant id was not found. | ' content: application/json: schema: description: Any type servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/{grantId}/revoke: post: operationId: revoke-grant summary: Revoke Grant description: Revokes a grant, rendering it unusable. Other endpoints will no longer be able to use the grant to perform its associated action. tags: - Grants parameters: - name: grantId in: path description: The unique identifier id of the grant to revoke required: true schema: type: string - name: Authorization in: header description: Basic authentication required: true schema: type: string responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GrantResponse' '403': description: '| errorCode | Description | | --- | --- | | feature_not_enabled | On file payments are not enabled for this merchant. | ' content: application/json: schema: description: Any type '404': description: '| errorCode | Description | | --- | --- | | grant_not_found | The specified grant was not found. | ' content: application/json: schema: description: Any type servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/alias: post: operationId: alias-grant summary: Create Grant Alias description: Creates an alias for an existing grant to help load the payment schedule widget. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: Accept in: header required: false schema: type: string default: application/json responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/GrantAliasResponse' '403': description: '| errorCode | Description | | --- | --- | | feature_not_enabled | On file payments are not enabled for this merchant. | ' content: application/json: schema: description: Any type '415': description: Unsupported Media Type - Content-Type header is missing or invalid content: application/json: schema: description: Any type requestBody: content: application/json: schema: $ref: '#/components/schemas/GrantAliasRequest' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/start: post: operationId: start-billing-agreement-link summary: Start Grant Link Flow description: Initiates the headless grant link flow process. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: Accept in: header required: false schema: type: string default: application/json responses: '201': description: Created content: application/json: schema: $ref: '#/components/schemas/GrantStartResponse' '404': description: '| errorCode | Description | | --- | --- | | not_found | Afterpay consumer account does not exist | ' content: application/json: schema: description: Any type '412': description: '| errorCode | Description | | --- | --- | | invalid_state | Failed to send code | ' content: application/json: schema: description: Any type '429': description: '| errorCode | Description | | --- | --- | | too_many_requests | Too many requests | ' content: application/json: schema: description: Any type requestBody: content: application/json: schema: $ref: '#/components/schemas/GrantStartRequest' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/retrieve: post: operationId: retrieve-grant summary: Retrieve Grant description: Retrieves a Cash App Pay customer grant by the ID of the customer that approved it and its own ID. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: User-Agent in: header required: true schema: type: string - name: Accept in: header description: Accept required: false schema: type: string default: application/json responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/retrieve-grant_Response_200' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/Retrieve-grantRequestUnauthorizedError' '403': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Retrieve-grantRequestForbiddenError' requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/RetrieveGrantRequest' servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production /v2/grants/revoke: post: operationId: postV2GrantsRevoke summary: Revoke Grant description: Revokes a Cash App Pay customer grant by the ID of the customer that approved it and its own ID. tags: - Grants parameters: - name: Authorization in: header description: Basic authentication required: true schema: type: string - name: User-Agent in: header required: true schema: type: string - name: Accept in: header description: Accept required: false schema: type: string default: application/json responses: '200': description: OK content: application/json: schema: $ref: '#/components/schemas/revoke-grant_Response_200' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/Revoke-grantRequestUnauthorizedError' '403': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Revoke-grantRequestForbiddenError' requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/RetrieveGrantRequest' x-operation-id-source: normalized x-operation-id-original: revoke-grant servers: - url: https://global-api-sandbox.afterpay.com description: Sandbox - url: https://global-api.afterpay.com description: Production components: schemas: GrantApprovalRequest: type: object properties: grants: type: array items: $ref: '#/components/schemas/GrantApprovalType' description: Grant type for approval (only single grant is supported) merchant: $ref: '#/components/schemas/GrantApprovalRequestMerchant' consumer: $ref: '#/components/schemas/Consumer' description: Consumer details for the grant required: - grants - merchant title: GrantApprovalRequest Consumer: type: object properties: email: type: string format: email givenNames: type: string description: The consumer's first name surname: type: string description: The consumer's last name phoneNumber: type: string required: - email description: The consumer data model is used for gathering essential user information. It captures details such as the individual's first name, represented by `givenNames`, and their last name, captured under `surname`. In addition, it stores the user's contact number under `phoneNumber` and their email address under `email`. These fields collectively provide contact and identification details for a user. title: Consumer GrantResponse: type: object properties: grant: $ref: '#/components/schemas/Grant' required: - grant title: GrantResponse GrantStatus: type: string enum: - ACTIVE - CANCELLED description: Current status of the grant title: GrantStatus CreateGrantRequest: type: object properties: requestId: type: string description: A unique request ID, required for idempotent retries. It is recommended that the merchant generate a UUID for each unique request. token: type: string description: The token returned from the create approval request. code: type: string description: 'The one-time code received from the consumer. Note: The code will only be sent with the headless integration.' required: - requestId - token title: CreateGrantRequest GrantApprovalType: type: object properties: type: $ref: '#/components/schemas/GrantApprovalTypeType' description: Grant Type for approval. merchantReference: type: - string - 'null' description: A merchant-provided reference for the grant. required: - type description: Details about the grant to be created. title: GrantApprovalType GrantAliasResponse: type: object properties: token: type: string description: Token representing the grant alias expiry: type: string format: date-time description: Timestamp when the alias token expires required: - token - expiry title: GrantAliasResponse GrantStartResponse: type: object properties: token: type: string description: Token identifying the grant to be created requestId: type: string description: The unique identifier from the request expiresAt: type: string format: date-time description: When this link attempt will expire deliveryType: $ref: '#/components/schemas/GrantStartResponseDeliveryType' description: How the verification code was delivered to the consumer required: - token - requestId - expiresAt - deliveryType title: GrantStartResponse GrantApprovalResponse: type: object properties: token: type: string description: Token identifying this grant approval request expires: type: string format: date-time description: When this approval request expires redirectCheckoutUrl: type: string format: uri description: URL where the consumer should be redirected to complete approval required: - token - expires - redirectCheckoutUrl title: GrantApprovalResponse GrantStartResponseDeliveryType: type: string enum: - SMS - EMAIL description: How the verification code was delivered to the consumer title: GrantStartResponseDeliveryType Grant: type: object properties: id: type: string description: Unique id identifying the grant type: $ref: '#/components/schemas/GrantType' description: Type of grant status: $ref: '#/components/schemas/GrantStatus' description: Current status of the grant created: type: string format: date-time description: Timestamp when the grant was created merchantReference: type: - string - 'null' description: Merchant's reference for this grant cancelled: type: string format: date-time description: If present, indicates when the grant was cancelled expires: type: string format: date-time description: If present, indicates when the grant's status will become EXPIRED, preventing a client from using it to create payments consumerReference: type: - string - 'null' description: Reference identifier for the consumer email: type: - string - 'null' description: Masked email address of the consumer requestId: type: - string - 'null' description: If present, unique identifier for the request required: - id - type - status - created title: Grant GrantApprovalTypeType: type: string enum: - ON_FILE description: Grant Type for approval. title: GrantApprovalTypeType GrantApprovalRequestMerchant: type: object properties: redirectConfirmUrl: type: string redirectCancelUrl: type: string popupOriginUrl: type: string description: This property is optional when a `redirectConfirmURL` is provided. name: type: string description: The merchant name displayed in the Afterpay approval flow. required: - redirectConfirmUrl - redirectCancelUrl title: GrantApprovalRequestMerchant GrantStartRequest: type: object properties: alias: type: string description: Email or phone number associated with the consumer's account requestId: type: string description: A unique identifier for this request required: - alias - requestId title: GrantStartRequest GrantAliasRequest: type: object properties: token: type: string description: Token of the grant to create an alias for duration: type: - string - 'null' format: duration description: Duration of the grant in ISO-8601 period format required: - token title: GrantAliasRequest GrantType: type: string enum: - ON_FILE description: Type of grant title: GrantType CashGrantIntent: type: string enum: - ON_FILE - ONE_TIME description: Either ON_FILE or ONE_TIME title: CashGrantIntent CashGrant: type: object properties: id: type: string description: Unique identifier for this grant issued by Cash App. intent: $ref: '#/components/schemas/CashGrantIntent' description: Either ON_FILE or ONE_TIME type: $ref: '#/components/schemas/CashGrantType' description: CASHAPP for all Cash App Pay transactions details: $ref: '#/components/schemas/CashGrantDetails' required: - id - intent - type - details description: Describes a grant provided by Cash App. title: CashGrant RetrieveGrantRequest: type: object properties: customerId: type: string description: ID of the customer that approved the customer grant. grantId: type: string description: ID of the customer grant to retrieve. required: - customerId - grantId title: RetrieveGrantRequest CashGrantDetails: type: object properties: status: $ref: '#/components/schemas/CashGrantDetailsStatus' description: 'Describes whether or not this grant can be used to perform the action associated with it. If `ACTIVE`, it can be used to perform the action. If `EXPIRED`, it may no longer be used to perform the action due to the current time being past the "expires_at" time. If `CONSUMED`, it was already redeemed to perform the action and cannot be used again. If `REVOKED`, the customer or merchant explicitly unauthorized the grant, preventing it from being used to perform the action. ' cashapp: $ref: '#/components/schemas/CashGrantDetailsCashapp' createdAt: type: string description: When this grant was created, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). updatedAt: type: string description: When this grant was last updated, in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). expiresAt: type: string description: 'If present, indicates when the grant''s status will become EXPIRED, preventing a client from using it to create payments or refunds. The timestamp is in the [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339) format (UTC). ' required: - status - cashapp - createdAt - updatedAt - expiresAt title: CashGrantDetails revoke-grant_Response_200: type: object properties: grant: $ref: '#/components/schemas/CashGrant' required: - grant title: revoke-grant_Response_200 CashGrantDetailsStatus: type: string enum: - ACTIVE - EXPIRED - CONSUMED - REVOKED description: 'Describes whether or not this grant can be used to perform the action associated with it. If `ACTIVE`, it can be used to perform the action. If `EXPIRED`, it may no longer be used to perform the action due to the current time being past the "expires_at" time. If `CONSUMED`, it was already redeemed to perform the action and cannot be used again. If `REVOKED`, the customer or merchant explicitly unauthorized the grant, preventing it from being used to perform the action. ' title: CashGrantDetailsStatus Revoke-grantRequestUnauthorizedError: type: object properties: errorCode: type: string errorId: type: string message: type: string httpStatusCode: type: integer title: Revoke-grantRequestUnauthorizedError CashGrantType: type: string enum: - CASHAPP description: CASHAPP for all Cash App Pay transactions title: CashGrantType Revoke-grantRequestForbiddenError: type: object properties: errorCode: type: string errorId: type: string message: type: string httpStatusCode: type: integer title: Revoke-grantRequestForbiddenError CashGrantDetailsCashapp: type: object properties: customerId: type: string cashtag: type: string description: A publicly-accessible, unique identifier (username) for individuals and businesses using Cash App. required: - customerId - cashtag title: CashGrantDetailsCashapp Retrieve-grantRequestForbiddenError: type: object properties: errorCode: type: string errorId: type: string message: type: string httpStatusCode: type: integer title: Retrieve-grantRequestForbiddenError Retrieve-grantRequestUnauthorizedError: type: object properties: errorCode: type: string errorId: type: string message: type: string httpStatusCode: type: integer title: Retrieve-grantRequestUnauthorizedError retrieve-grant_Response_200: type: object properties: grant: $ref: '#/components/schemas/CashGrant' required: - grant title: retrieve-grant_Response_200 securitySchemes: sec0: type: http scheme: basic x-refined-from: - cash-app-grants-afterpay-openapi.json - cash-app-grants-cash-app-pay-openapi.json