Mangopay Recurring Apple Pay Payins API

openapi: 3.2.0
info:
  title: Reference Recurring Apple Pay Payins API
  version: 1.0.0
servers:
- url: https://api.sandbox.mangopay.com
  description: Sandbox
- url: https://api.mangopay.com
  description: Production
- url: https://api-mtls.sandbox.mangopay.com
  description: mTLS Sandbox
- url: https://api-mtls.mangopay.com
  description: mTLS Production
- url: '%7BCardRegistrationUrl%7D'
  description: "The full dynamic URL returned by the Create a Card Registration call, including host, path, and query parameters. \n"
- url: '%7BSettlementFileUploadUrl%7D'
  description: 'The unique URL returned by the [POST Create a Settlement and secure URL](/api-reference/settlements/create-settlement) endpoint.


    **Note:** Use the full dynamic URL including the host, path, and all query parameters. The URL is already authenticated, so this call does not require an Authorization header.

    '
tags:
- name: recurringApplePayPayins
paths:
  /v2.01/{ClientId}/payins/payment-methods/applepay/recurring:
    post:
      operationId: recurringApplePayPayins_create_recurring_apple_pay_payin
      summary: Create a Recurring Apple Pay PayIn (CIT or MIT)
      description: 'Request a recurring Apple Pay pay-in based on a `RecurringPayinRegistrationId` with `PaymentType` `APPLEPAY`, obtained from POST Create a Recurring PayIn Registration.


        There are two possible paylods:

        - **CIT** – Customer-initiated transaction when the user is on session. With Apple Pay, authentication is handled by the user''s device (iPhone or Mac) so there is no need for redirection.

        - **MIT** – Subsequent merchant-initiated transactions in the absence of the user, based on the initial successful authentication, unless and until re-authentication is required.


        Read more about Apple Pay recurring payments **→**'
      tags:
      - recurringApplePayPayins
      parameters:
      - name: ClientId
        in: path
        description: Platform's API account identifier, associated with the API key.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringApplePayPayInResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/recurringApplePayPayins_create_recurring_apple_pay_payin_Request'
      security:
      - oauth2: []
components:
  schemas:
    RecurringApplePayPayInResponseDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the debited funds. The values must match those requested from Apple Pay, because they are encrypted in the `PaymentData`.
      title: RecurringApplePayPayInResponseDebitedFunds
    recurringApplePayPayins_create_recurring_apple_pay_payin_Request:
      oneOf:
      - $ref: '#/components/schemas/CreateARecurringApplePayPayInCITRequest'
      - $ref: '#/components/schemas/CreateARecurringApplePayPayInMITRequest'
      title: recurringApplePayPayins_create_recurring_apple_pay_payin_Request
    AuthenticationResult:
      type: object
      properties:
        AuthenticationType:
          type:
          - string
          - 'null'
          description: '**Returned values:** `CHALLENGE`, `FRICTIONLESS`, `DIRECT_AUTHORIZATION`


            The type of authentication:


            - `CHALLENGE` – The issuer requested SCA to be enforced (for example, using 3DS).

            - `FRICTIONLESS` – The transaction was exempted from SCA because an exemption was granted by the issuer.

            - `DIRECT_AUTHORIZATION` – The transaction was sent to the issuer for authorization without any frictionless or challenge (for example, if SCA doesn''t apply). A `null` value typically indicates that authentication was not requested (for example, because the request failed before being sent) or a decision was not received.


            A `null` value typically indicates that authentication was not requested (for example, because the request failed before being sent) or a decision was not received.'
      description: Information about the authentication result, based on the request made by Mangopay and the decision of the issuer regarding the type of authentication to be enforced (if applicable).
      title: AuthenticationResult
    Amount:
      type: integer
      description: The amount of the currency in its minor unit. For example, EUR 12.60 would be represented as `1260` whereas JPY 12 would be represented as just `12`.
      title: Amount
    CreateARecurringApplePayPayInMitRequestDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: 'Information about the debited funds. This property overrides the `NextTransactionDebitedFunds` of the Registration, and is **required if** that property is empty.


        **Caution:** An amount must be provided in either the Registration''s `NextTransactionDebitedFunds` or the pay-in''s `DebitedFunds`.'
      title: CreateARecurringApplePayPayInMitRequestDebitedFunds
    PaymentCategory:
      type: string
      description: '**Default value:** `ECommerce`


        **Allowed values:** `ECommerce`, `TelephoneOrder`


        The channel through which the user provided their card details, used to indicate mail-order and telephone-order (MOTO) payments:

        - `ECommerce` – Payment received online.

        - `TelephoneOrder` – Payment received via mail order or telephone order (MOTO).'
      title: PaymentCategory
    CreateARecurringApplePayPayInMitRequestFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: 'Information about the fees. This property overrides the `NextTransactionFees` of the Registration, and is **required if** that property is empty.


        **Caution:** An amount must be provided in either the Registration''s `NextTransactionFees` or the pay-in''s `Fees`.'
      title: CreateARecurringApplePayPayInMitRequestFees
    PreferredCardNetwork_ApplePay:
      type:
      - string
      - 'null'
      description: Not applicable to Apple Pay pay-ins, so this value is returned `null`. For Apple Pay, the network is resolved by Apple Pay and returned in `PaymentData.Network` instead.
      title: PreferredCardNetwork_ApplePay
    AuthorId:
      type: string
      description: The unique identifier of the user at the source of the transaction.
      title: AuthorId
    RecurringApplePayPayInResponse:
      type: object
      properties:
        Id:
          $ref: '#/components/schemas/Id'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreationDate:
          $ref: '#/components/schemas/CreationDate'
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        DebitedFunds:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseDebitedFunds'
          description: Information about the debited funds. The values must match those requested from Apple Pay, because they are encrypted in the `PaymentData`.
        CreditedFunds:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseCreditedFunds'
          description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
        Fees:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseFees'
          description: Information about the fees.
        Status:
          $ref: '#/components/schemas/TransactionStatus'
        ResultCode:
          $ref: '#/components/schemas/ResultCode'
        ResultMessage:
          $ref: '#/components/schemas/ResultMessage'
        ExecutionDate:
          $ref: '#/components/schemas/TransactionExecutionDate'
        Type:
          $ref: '#/components/schemas/TransactionType'
        Nature:
          $ref: '#/components/schemas/TransactionNature'
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet.
        CreditedUserId:
          $ref: '#/components/schemas/CreditedUserId'
        PaymentType:
          type: string
          description: '**Returned values:** `APPLEPAY`


            The payment type of the pay-in.'
        ExecutionType:
          type: string
          description: '**Returned values:** `DIRECT`


            The execution type of the pay-in.'
        StatementDescriptor:
          $ref: '#/components/schemas/StatementDescriptor_22'
        DebitedWalletId:
          type: string
          description: 'The unique identifier of the debited wallet.


            In the case of a pay-in, this value is always `null` since there is no debited wallet.'
        SecurityInfo:
          $ref: '#/components/schemas/AVSResult'
        SecureMode:
          type: string
          description: The mode applied for the 3DS2 protocol. On Apple Pay, this value is returned `null` as 3DS redirection is not applicable.
        CardId:
          type: string
          description: For Apple Pay recurring registrations, this value is returned `null`.
        SecureModeReturnURL:
          type: string
          description: 'Max. length: 255 characters


            The URL to which users are automatically returned after 3DS2 if it is triggered. On Apple Pay, `null` is returned as 3DS redirection does not apply.'
        SecureModeRedirectURL:
          type: string
          description: 'Max. length: 255 characters


            The URL to which to redirect the user to proceed to 3DS2 validation. On Apple Pay, `null` is returned as 3DS redirection does not apply.'
        SecureModeNeeded:
          type: boolean
          description: Whether or not the `SecureMode` was used.
        Culture:
          type: string
          description: The language in which the payment page is to be displayed. On Apple Pay, `null` is returned.
        BrowserInfo:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseBrowserInfo'
          description: Information about the browser used by the end user (author) to perform the payment. On Apple Pay, `null` is returned as 3DS redirection does not apply.
        IpAddress:
          type: string
          description: The IP address of the end user initiating the transaction, in IPV4 or IPV6 format. On Apple Pay, `null` is returned as 3DS redirection does not apply.
        Requested3DSVersion:
          type: string
          description: '**Returned values:** `V1`, `V2_1`


            The 3DS protocol version to be applied to the transaction.'
        Applied3DSVersion:
          type: string
          description: '**Returned values:** `V1`, `V2_1`


            The 3DS protocol version applied to the transaction.'
        RecurringPayinRegistrationId:
          type: string
          description: The unique identifier of the recurring pay-in registration.
        PreferredCardNetwork:
          $ref: '#/components/schemas/PreferredCardNetwork_ApplePay'
        PaymentCategory:
          $ref: '#/components/schemas/PaymentCategory'
        CardInfo:
          $ref: '#/components/schemas/CardInfo'
        AuthenticationResult:
          $ref: '#/components/schemas/AuthenticationResult'
        Billing:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseBilling'
          description: Information about the end user billing address. On Apple Pay, `null` is returned as 3DS redirection does not apply.
        Shipping:
          $ref: '#/components/schemas/RecurringApplePayPayInResponseShipping'
          description: Information about the end user's shipping address. On Apple Pay, `null` is returned as 3DS redirection does not apply.
      description: 'A recurring Apple Pay pay-in:

        - `PaymentType` – `APPLEPAY`

        - `ExecutionType` – `DIRECT`

        - Object includes `RecurringPayinRegistrationId`'
      title: RecurringApplePayPayInResponse
    TransactionExecutionDate:
      type: integer
      description: Unix timestamp (UTC) of the date and time the status changed to `SUCCEEDED`, indicating that the transaction occurred. The statuses `CREATED` and `FAILED` return an `ExecutionDate` of `null`.
      title: TransactionExecutionDate
    CreateARecurringApplePayPayInMITRequest:
      type: object
      properties:
        Tag:
          $ref: '#/components/schemas/Tag'
        DebitedFunds:
          $ref: '#/components/schemas/CreateARecurringApplePayPayInMitRequestDebitedFunds'
          description: 'Information about the debited funds. This property overrides the `NextTransactionDebitedFunds` of the Registration, and is **required if** that property is empty.


            **Caution:** An amount must be provided in either the Registration''s `NextTransactionDebitedFunds` or the pay-in''s `DebitedFunds`.'
        Fees:
          $ref: '#/components/schemas/CreateARecurringApplePayPayInMitRequestFees'
          description: 'Information about the fees. This property overrides the `NextTransactionFees` of the Registration, and is **required if** that property is empty.


            **Caution:** An amount must be provided in either the Registration''s `NextTransactionFees` or the pay-in''s `Fees`.'
        StatementDescriptor:
          $ref: '#/components/schemas/StatementDescriptor_22'
        RecurringPayinRegistrationId:
          type: string
          description: The unique identifier of the recurring pay-in registration.
      required:
      - DebitedFunds
      - RecurringPayinRegistrationId
      description: Request body for an Apple Pay merchant-initiated transaction (MIT).
      title: CreateARecurringApplePayPayInMITRequest
    RecurringApplePayPayInResponseShipping:
      type: object
      properties: {}
      description: Information about the end user's shipping address. On Apple Pay, `null` is returned as 3DS redirection does not apply.
      title: RecurringApplePayPayInResponseShipping
    TransactionStatus:
      type: string
      description: '**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`


        The status of the transaction.'
      title: TransactionStatus
    RecurringApplePayPayInResponseBrowserInfo:
      type: object
      properties: {}
      description: Information about the browser used by the end user (author) to perform the payment. On Apple Pay, `null` is returned as 3DS redirection does not apply.
      title: RecurringApplePayPayInResponseBrowserInfo
    CreditedUserId:
      type: string
      description: '**Default value:** The unique identifier of the owner of the credited wallet.


        The unique identifier of the user whose wallet is credited.'
      title: CreditedUserId
    ResultMessage:
      type: string
      description: The explanation of the result code.
      title: ResultMessage
    Currency:
      type: string
      description: '**Allowed values:** The three-letter <a href="/api-reference/overview/data-formats" target="_blank">ISO 4217 code</a> (EUR, GBP, etc.) of a <a href="/guides/currencies" target="_blank">supported currency</a> (depends on feature, contract, and activation settings).


        The currency of the amount.'
      title: Currency
    StatementDescriptor_22:
      type: string
      description: 'Max. length: 22 characters; only alphanumeric and spaces


        Custom description to appear on the user’s bank statement along with the platform name. Different banks may show more or less information. See the <a href="/bank-statements">Customizing bank statement references</a> article for details.'
      title: StatementDescriptor_22
    TransactionNature:
      type: string
      description: '**Returned values:** `REGULAR`, `REPUDIATION`, `REFUND`, `SETTLEMENT`


        The nature of the transaction, providing more information about the context in which the transaction occurred:

        - `REGULAR` – Relative to most of the transactions (pay-ins, payouts, and transfers) in a usual workflow.

        - `REPUDIATION` – Automatic withdrawal of funds from the platform''s repudiation wallet as part of the dispute process (when the user has requested a chargeback).

        - `REFUND` – Reimbursement of a transaction to the user (pay-in refund), to a wallet (transfer refund), or of a payout (payout refund, only initiated by Mangopay).

        - `SETTLEMENT` – Transfer made to the repudiation wallet by the platform to settle a lost dispute.'
      title: TransactionNature
    AVSResult:
      type: object
      properties:
        AVSResult:
          type: string
          description: The result of the Address Verification System check (only available for UK, US, and Canada).
      description: Information regarding security and anti-fraud tools.
      title: AVSResult
    Tag:
      type: string
      description: 'Max. length: 255 characters


        Custom data that you can add to this object, such as unique identifiers in your system. To store multiple values, you can serialize them into a single string, for example a JSON object: `"{\"id_1\":AB123,\"id_2\":DE456}"`.'
      title: Tag
    CreationDate:
      type: integer
      description: Unix timestamp (UTC) of the date and time the object was created.
      title: CreationDate
    CreateARecurringApplePayPayInCITRequest:
      type: object
      properties:
        RecurringPayinRegistrationId:
          type: string
          description: The unique identifier of the recurring pay-in registration.
        Tag:
          $ref: '#/components/schemas/Tag'
      required:
      - RecurringPayinRegistrationId
      description: Request body for an Apple Pay customer-initiated transaction (CIT).
      title: CreateARecurringApplePayPayInCITRequest
    Id:
      type: string
      description: 'Max length: 128 characters (see [data formats](/api-reference/overview/data-formats) for details)


        The unique identifier of the object.'
      title: Id
    RecurringApplePayPayInResponseFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the fees.
      title: RecurringApplePayPayInResponseFees
    RecurringApplePayPayInResponseCreditedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
      title: RecurringApplePayPayInResponseCreditedFunds
    RecurringApplePayPayInResponseBilling:
      type: object
      properties: {}
      description: Information about the end user billing address. On Apple Pay, `null` is returned as 3DS redirection does not apply.
      title: RecurringApplePayPayInResponseBilling
    ResultCode:
      type: string
      description: The code indicating the result of the operation. This information is mostly used to <a href="/errors/codes">handle errors</a> or for filtering purposes.
      title: ResultCode
    TransactionType:
      type: string
      description: '**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`


        The type of the transaction.'
      title: TransactionType
    CardInfo:
      type: object
      properties:
        BIN:
          type: string
          description: The bank identification number (BIN) of the card.
        IssuingBank:
          type: string
          description: The name of the bank that issued the card.
        IssuerCountryCode:
          type: string
          description: The country code of the card issuer.
        Type:
          type: string
          description: The type of card (for example, `CREDIT` or `DEBIT`).
        SubType:
          type:
          - string
          - 'null'
          description: The sub-type of the card, if available.
        Brand:
          type: string
          description: The card brand (for example, `VISA` or `MASTERCARD`).
      description: Information about the card used for the transaction. If the information or data is not available, `null` is returned.
      title: CardInfo
  securitySchemes:
    oauth2:
      type: http
      scheme: bearer
      description: "Bearer authentication of the form `Bearer <token>`, where token is your auth token. \n\nIf your platform is using a [proxy](/guides/sca/proxy-management) to take SCA-triggering action on behalf of users, you also need to integrate [mTLS authentication](/guides/sca/platform) and use the `api-mtls` base URL."
x-provenance:
  method: harvested
  publisher: Mangopay
  source: https://docs.mangopay.com/openapi.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)