Cash App Recurring Payments API

openapi: 3.2.0
info:
  title: Billing Agreements (Deprecated) Recurring Payments API
  version: 1.0.0
servers:
- url: https://global-api-sandbox.afterpay.com
  description: Sandbox
- url: https://global-api.afterpay.com
  description: Production
tags:
- name: Recurring Payments
paths:
  /v2/recurring-payments:
    post:
      operationId: capture-full-recurring-payment
      summary: Capture Full Recurring Payment
      description: 'Creates and immediately captures a recurring payment using a billing agreement token.

        This endpoint combines authorization and capture into a single step.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Recurring Payments
      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
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '201':
          description: '| Status | Description |

            | ----- | ----- |

            | `APPROVED` | If payment is approved by Afterpay, returns a Payment object in response, with a status of "APPROVED". |

            | `DECLINED` | If payment is declined by Afterpay, for example, if expired payment method, returns a Payment object in response, with a status of "DECLINED". Please advise the consumer to contact the Afterpay Customer Service team for more information. |

            '
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Payment'
        '402':
          description: 'If payment is declined by Afterpay, for example, if invalid card details were entered, returns a Payment object in response, with a `status` of "DECLINED" and a `paymentState` of "AUTH_DECLINED". Please advise the consumer to contact the Afterpay Customer Service team for more information.


            As well, the following errorCodes are possible:

            | errorCode | Description |

            | --- | --- |

            | invalid_token | The checkout token is invalid, expired, or does not exist.

            '
          content:
            application/json:
              schema:
                description: Any type
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_object             | One or more required fields were missing or invalid.                     |

            | unsupported_payment_type   | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            | unsupported_currency       | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the payment details to process
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringPaymentRequest'
  /v2/recurring-payments/auth:
    post:
      operationId: auth
      summary: Authorize Recurring Payment
      description: 'Authorizes a recurring payment using a billing agreement token.

        This endpoint performs authorization only, requiring a separate capture step.


        *Deprecated. For new integrations, see Grants.*'
      tags:
      - Recurring Payments
      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
        required: false
        schema:
          type: string
          default: application/json
      responses:
        '201':
          description: If the payment is approved by Afterpay, a Payment object is returned with a `status` of **APPROVED** and a `paymentState` of **AUTH_APPROVED**.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentAuth'
        '402':
          description: 'If payment is declined by Afterpay, for example, if invalid card details were entered, returns a Payment object in response, with a `status` of "DECLINED" and a `paymentState` of "AUTH_DECLINED". Please advise the consumer to contact the Afterpay Customer Service team for more information.


            As well, the following errorCodes are possible:

            | errorCode | Description |

            | --- | --- |

            | invalid_token | The checkout token is invalid, expired, or does not exist.

            '
          content:
            application/json:
              schema:
                description: Any type
        '412':
          description: '| errorCode | Description |

            | --- | --- |

            |npuf_eligibility_mismatch|Npuf eligibility mismatch|

            '
          content:
            application/json:
              schema:
                description: Any type
        '415':
          description: Unsupported Media Type
          content:
            application/json:
              schema:
                description: Any type
        '422':
          description: '| errorCode | Description |

            | --- | --- |

            | invalid_object             | One or more required fields were missing or invalid.                     |

            | unsupported_payment_type   | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            | unsupported_currency       | The amount is outside of the merchant''s payment limits, as returned by Get Configuration. |

            '
          content:
            application/json:
              schema:
                description: Any type
      requestBody:
        description: The request containing the payment details to authorize
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RecurringPaymentRequest'
components:
  schemas:
    PaymentStatus:
      type: string
      enum:
      - APPROVED
      - DECLINED
      description: represents the status of the order
      title: PaymentStatus
    RecurringPaymentRequestEnrichmentsInitiationActor:
      type: string
      enum:
      - CUSTOMER
      - MERCHANT
      description: The actor initiating the transaction. Use MERCHANT when the customer is not present.
      title: RecurringPaymentRequestEnrichmentsInitiationActor
    Payment-Event:
      type: object
      properties:
        id:
          type: string
        created:
          type: string
        expires:
          type: string
        type:
          $ref: '#/components/schemas/PaymentEventType'
        amount:
          $ref: '#/components/schemas/Money'
        paymentEventMerchantReference:
          type: string
      description: Each payment event has a unique ID, creation timestamp, and type (e.g., "AUTH_APPROVED", "AUTH_DECLINED"). For "AUTH_APPROVED" events, an expiration timestamp is provided. The "payment event merchant reference" field, which can be used for payment capture events
      title: Payment-Event
    RecurringPaymentRequestPaymentMethod:
      type: object
      properties:
        token:
          type: string
          description: The billing agreement token
        type:
          $ref: '#/components/schemas/RecurringPaymentRequestPaymentMethodType'
          description: The payment method type
      required:
      - token
      - type
      title: RecurringPaymentRequestPaymentMethod
    PaymentPaymentState:
      type: string
      enum:
      - AUTH_APPROVED
      - AUTH_DECLINED
      - PARTIALLY_CAPTURED
      - CAPTURED
      - CAPTURE_DECLINED
      - VOIDED
      description: is the current state for capturing payments
      title: PaymentPaymentState
    PaymentAuthStatus:
      type: string
      enum:
      - APPROVED
      - DECLINED
      description: represents the status of the order
      title: PaymentAuthStatus
    ShippingCourierPriority:
      type: string
      enum:
      - STANDARD
      - EXPRESS
      title: ShippingCourierPriority
    Order-Details:
      type: object
      properties:
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
      description: This comprehensive schema is designed to store an entire transaction's detail, covering crucial aspects like consumer information, billing and shipping details, courier particulars, item list, discounts, tax, and shipping amount.
      title: Order-Details
    Contact:
      type: object
      properties:
        name:
          type: string
        line1:
          type: string
          description: First line of the address
        line2:
          type: string
          description: 'Second line of the address '
        area1:
          type: string
          description: '- AU: Suburb

            - NZ: Town or City

            - UK: Postal Town

            - US: City

            - Canada: City'
        area2:
          type: string
          description: '- NZ: suburb

            - UK: village or local area.'
        region:
          type: string
          description: "- AU: State \n- NZ: Region\n- UK: County\n- US: State\n- CA: Province or Territory"
        postcode:
          type: string
        countryCode:
          $ref: '#/components/schemas/ContactCountryCode'
        phoneNumber:
          type: string
          description: The phone number, in [E.123](https://en.wikipedia.org/wiki/E.123) format.
      required:
      - name
      - line1
      - area1
      - region
      - postcode
      - countryCode
      description: "This data model is used for storing an individual's contact information. Mandatory fields such as **name**, **line1**, **area1**, **region**, **postcode**, and **countryCode** help in capturing vital information about a user's location. \n\nThe `line2` and `area2` fields provide additional space for extended addresses, while `phoneNumber` can be used to store the user's contact number.\n\n\n<Warning Title=\"Important Note\">\n  The `area1`, `area2` and `region` properties feature localized terminology based on country. Refer to the property descriptions for insights on each country's specific usage \n</Warning>\n"
      title: Contact
    RecurringPaymentRequestMerchant:
      type: object
      properties:
        name:
          type: string
          description: The merchant name to display
      title: RecurringPaymentRequestMerchant
    Discount:
      type: object
      properties:
        displayName:
          type: string
        amount:
          $ref: '#/components/schemas/Money'
      description: Discount applied to an order
      title: Discount
    PaymentAuthPaymentState:
      type: string
      enum:
      - AUTH_APPROVED
      - AUTH_DECLINED
      - PARTIALLY_CAPTURED
      - CAPTURED
      - CAPTURE_DECLINED
      - VOIDED
      description: is the current state for capturing payments
      title: PaymentAuthPaymentState
    RecurringPaymentRequestEnrichmentsInitiation:
      type: object
      properties:
        actor:
          $ref: '#/components/schemas/RecurringPaymentRequestEnrichmentsInitiationActor'
          description: The actor initiating the transaction. Use MERCHANT when the customer is not present.
      description: Describes who initiated the transaction
      title: RecurringPaymentRequestEnrichmentsInitiation
    RecurringPaymentRequestEnrichments:
      type: object
      properties:
        initiation:
          $ref: '#/components/schemas/RecurringPaymentRequestEnrichmentsInitiation'
          description: Describes who initiated the transaction
      title: RecurringPaymentRequestEnrichments
    Refund:
      type: object
      properties:
        requestId:
          type: string
          description: Unique ID required for safe retries. Max length 64 (varchar).
        amount:
          $ref: '#/components/schemas/Money'
        merchantReference:
          type: string
          description: The merchant’s internal refund id/reference. This must be included along with the `requestId` to utilise idempotency. Max length 85 (varchar).
        refundMerchantReference:
          type: string
          description: A unique reference for the individual refund event. Max length 128 (varchar).
        refundId:
          type: string
          description: The unique, permanent, Afterpay-generated Refund ID.
        refundedAt:
          type: string
      description: 'To guarantee safe retries, the merchant should offer their refund ID or reference, aligning with their internal records


        Unique values for the `requestID`  and `merchantReference` are required to guarantee safe retries. It is recommended that the merchant generates a UUID for each unique refund request.


        The `refundMerchantReference` is a unique reference that when provided, will appear in the daily settlement file as "Payment Event Id". In most cases, this would hold the same value as the `merchantReference`.

        '
      title: Refund
    RecurringPaymentRequest:
      type: object
      properties:
        requestId:
          type: string
          format: uuid
          description: A unique identifier for the request, used for idempotency
        paymentMethod:
          $ref: '#/components/schemas/RecurringPaymentRequestPaymentMethod'
        amount:
          $ref: '#/components/schemas/Money'
          description: The total amount of the payment
        consumer:
          $ref: '#/components/schemas/Consumer'
        billing:
          $ref: '#/components/schemas/Contact'
        shipping:
          $ref: '#/components/schemas/Contact'
        courier:
          $ref: '#/components/schemas/Shipping-Courier'
        items:
          type: array
          items:
            $ref: '#/components/schemas/Item'
        discounts:
          type: array
          items:
            $ref: '#/components/schemas/Discount'
        description:
          type: string
        merchant:
          $ref: '#/components/schemas/RecurringPaymentRequestMerchant'
        merchantReference:
          type: string
          description: The reference/order ID in the merchant's system
        shippingAmount:
          $ref: '#/components/schemas/Money'
          description: The shipping cost amount
        taxAmount:
          $ref: '#/components/schemas/Money'
          description: The tax amount
        custom:
          type: object
          additionalProperties:
            description: Any type
          description: Custom key-value pairs for merchant use
        paymentScheduleChecksum:
          type: string
          description: Payment schedule validation checksum
        enrichments:
          $ref: '#/components/schemas/RecurringPaymentRequestEnrichments'
      required:
      - requestId
      - paymentMethod
      - amount
      title: RecurringPaymentRequest
    Shipping-Courier:
      type: object
      properties:
        shippedAt:
          type: string
          format: date-time
        name:
          type: string
        tracking:
          type: string
        priority:
          $ref: '#/components/schemas/ShippingCourierPriority'
      description: 'Essential information for tracking a shipment. The `shippedAt` key represents the date and time when the item was shipped. This value follows the [ISO 8601 standard format](https://www.iso.org/iso-8601-date-and-time-format.html) for date and time representations.


        The `name` field indicates the courier service employed to handle the shipment (e.g. FEDEX, UPS). For orders that are picked up in-store (also known as Buy-Online-Pickup-Instore), please use "INSTORE_PICKUP" as the `name` field value.


        The `tracking` key represents a unique tracking number provided by the courier service to monitor the shipment''s progress. It''s a valuable tool for customers and businesses to track and trace their packages.


        The `priority` field tracks the shipping speed or service level associated with the delivery. '
      title: Shipping-Courier
    PaymentEventType:
      type: string
      enum:
      - AUTH_APPROVED
      - AUTH_DECLINED
      - CAPTURED
      - CAPTURE_DECLINED
      - VOIDED
      - EXPIRED
      title: PaymentEventType
    Item:
      type: object
      properties:
        name:
          type: string
        sku:
          type: string
        pageUrl:
          type: string
        imageUrl:
          type: string
        quantity:
          type: integer
        price:
          $ref: '#/components/schemas/Money'
        categories:
          type: array
          items:
            type: array
            items:
              type: string
        estimatedShipmentDate:
          type: string
          format: date
        preorder:
          type: boolean
          default: false
      required:
      - name
      - quantity
      - price
      description: "This data model is used to store crucial product details. The `price.amount` field represents the unit price of the individual item. The `quantity` field shows the number of units of the item. The `name` field denotes the name of the product, while `sku` holds the Stock Keeping Unit identifier. 100 is the maximum number of item objects in the items array.\n<Warning Title=\"Important Note\">\n  It is crucial that the `price.amount` represents the unit price of the individual item.\n  **Never** populate the `price.amount` by multiplying the quantity by the unit cost. Always enter the price for a single unit to maintain data accuracy.\n</Warning>\n"
      title: Item
    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
    MoneyCurrency:
      type: string
      enum:
      - AUD
      - NZD
      - USD
      - CAD
      - GBP
      title: MoneyCurrency
    Payment:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: is the merchant's order id/reference that the payment corresponds to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'
      description: Describes the schema for a (read-only) payment object
      title: Payment
    RecurringPaymentRequestPaymentMethodType:
      type: string
      enum:
      - BILLING_AGREEMENT
      description: The payment method type
      title: RecurringPaymentRequestPaymentMethodType
    PaymentAuth:
      type: object
      properties:
        id:
          type: string
          description: The unique, permanent, Afterpay generated Order ID.
        token:
          type: string
          description: The token obtained from the checkout call
        status:
          $ref: '#/components/schemas/PaymentAuthStatus'
          description: represents the status of the order
        created:
          type: string
          description: ' is the UTC timestamp of when the payment was completed.'
        originalAmount:
          $ref: '#/components/schemas/Money'
        openToCaptureAmount:
          $ref: '#/components/schemas/Money'
        paymentState:
          $ref: '#/components/schemas/PaymentAuthPaymentState'
          description: is the current state for capturing payments
        merchantReference:
          type: string
          description: is the merchant's order id/reference that the payment corresponds to.
        refunds:
          type: array
          items:
            $ref: '#/components/schemas/Refund'
        orderDetails:
          $ref: '#/components/schemas/Order-Details'
        events:
          type: array
          items:
            $ref: '#/components/schemas/Payment-Event'
      description: Describes the schema for a (read-only) payment object
      title: PaymentAuth
    ContactCountryCode:
      type: string
      enum:
      - AU
      - NZ
      - US
      - CA
      - GB
      title: ContactCountryCode
    Money:
      type: object
      properties:
        amount:
          type: string
          description: The amount as a string representation of a decimal number, rounded to 2 decimal places.
        currency:
          $ref: '#/components/schemas/MoneyCurrency'
      required:
      - amount
      - currency
      description: Object containing amount and currency
      title: Money
  securitySchemes:
    sec0:
      type: http
      scheme: basic