Mangopay Blik API

openapi: 3.2.0
info:
  title: Reference Blik 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: Blik
paths:
  /v2.01/{ClientId}/payins/payment-methods/blik:
    post:
      operationId: blik_create_blik_payin
      summary: Create a BLIK PayIn
      description: '**Note – Timeout after 55 seconds**


        The payment session lasts for 55 seconds, at which point the pay-in fails automatically if no action has been taken by the user.


        **Note – Minimum amount in Production**


        In Production, the minimum accepted amount for BLIK is 0.01 PLN (`1`).'
      tags:
      - Blik
      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/BLIKPayInResponse'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/blik_create_blik_payin_Request'
      security:
      - oauth2: []
components:
  schemas:
    CreateAblikPayInWithCodeRequestBrowserInfo:
      type: object
      properties:
        UserAgent:
          type: string
          description: The exact content of the HTTP User-Agent header.
        JavascriptEnabled:
          type: boolean
          description: Whether or not the end user's browser has the ability to execute JavaScript.
      required:
      - UserAgent
      - JavascriptEnabled
      description: Information about the browser used by the end user (author) to perform the payment.
      title: CreateAblikPayInWithCodeRequestBrowserInfo
    StatementDescriptor:
      type: string
      description: 'Max. length: 10 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
    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
    FlowDescriptorRequestBeneficiariesItems:
      type: object
      properties:
        UserId:
          type: string
          description: The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in.
      title: FlowDescriptorRequestBeneficiariesItems
    BlikPayInResponseFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the fees.
      title: BlikPayInResponseFees
    BlikPayInResponseCreditedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
      title: BlikPayInResponseCreditedFunds
    BlikPayInResponseBrowserInfo:
      type: object
      properties:
        UserAgent:
          type: string
          description: The exact content of the HTTP User-Agent header.
        JavascriptEnabled:
          type: boolean
          description: Whether or not the end user's browser has the ability to execute JavaScript.
      description: Information about the browser used by the end user (author) to perform the payment.
      title: BlikPayInResponseBrowserInfo
    FlowDescriptorResponseBeneficiariesItems:
      type: object
      properties:
        UserId:
          type: string
          description: The unique identifier of the Natural User or Legal User declared as a beneficiary of the pay-in.
      title: FlowDescriptorResponseBeneficiariesItems
    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
    CreateAblikPayInWithCodeRequestFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: Information about the fees.
      title: CreateAblikPayInWithCodeRequestFees
    AuthorId:
      type: string
      description: The unique identifier of the user at the source of the transaction.
      title: AuthorId
    CreateABLIKPayInWithoutCodeRequest:
      type: object
      properties:
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet.
        FlowDescriptor:
          $ref: '#/components/schemas/FlowDescriptorRequest'
        DebitedFunds:
          $ref: '#/components/schemas/CreateAblikPayInWithoutCodeRequestDebitedFunds'
          description: Information about the debited funds.
        Fees:
          $ref: '#/components/schemas/CreateAblikPayInWithoutCodeRequestFees'
          description: Information about the fees.
        ReturnURL:
          $ref: '#/components/schemas/ReturnURL_255'
        StatementDescriptor:
          $ref: '#/components/schemas/StatementDescriptor'
      required:
      - AuthorId
      - CreditedWalletId
      - DebitedFunds
      - Fees
      - ReturnURL
      description: BLIK pay-in request body if the user has previously saved your platform, relying only on redirection.
      title: CreateABLIKPayInWithoutCodeRequest
    FlowDescriptorRequest:
      type: object
      properties:
        Beneficiaries:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FlowDescriptorRequestBeneficiariesItems'
          description: 'Max. length: 5 items


            The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values.'
      description: "Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n  - `OWNER` whose `KYCLevel` is `REGULAR`\n  - `PLATFORM`\n  \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`. \n"
      title: FlowDescriptorRequest
    BlikPayInResponseDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      description: Information about the debited funds.
      title: BlikPayInResponseDebitedFunds
    BLIKPayInResponse:
      type: object
      properties:
        Id:
          $ref: '#/components/schemas/Id'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreationDate:
          $ref: '#/components/schemas/CreationDate'
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        FlowDescriptor:
          $ref: '#/components/schemas/FlowDescriptorResponse'
        DebitedFunds:
          $ref: '#/components/schemas/BlikPayInResponseDebitedFunds'
          description: Information about the debited funds.
        CreditedFunds:
          $ref: '#/components/schemas/BlikPayInResponseCreditedFunds'
          description: Information about the credited funds (`CreditedFunds` = `DebitedFunds` - `Fees`).
        Fees:
          $ref: '#/components/schemas/BlikPayInResponseFees'
          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.
        PaymentType:
          type: string
          description: '**Returned values:** `BLIK`


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


            The execution type of the pay-in.'
        ReturnURL:
          $ref: '#/components/schemas/ReturnURL_255'
        RedirectURL:
          type: string
          description: 'The URL to which to redirect the user to complete the payment.


            **Caution:** This variable URL is specific to each payment. You must rely on the returned URL in full (host, path, and queries) and not hardcode any part of it.'
        StatementDescriptor:
          $ref: '#/components/schemas/StatementDescriptor'
        Code:
          type:
          - string
          - 'null'
          description: The 6-digit code sent in the request (otherwise returned `null`).
        BrowserInfo:
          oneOf:
          - $ref: '#/components/schemas/BlikPayInResponseBrowserInfo'
          - type: 'null'
          description: Information about the browser used by the end user (author) to perform the payment.
        IpAddress:
          type:
          - string
          - 'null'
          description: The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
      description: 'A BLIK pay-in:

        - `PaymentType` – `BLIK`

        - `ExecutionType` – `WEB`'
      title: BLIKPayInResponse
    CreateAblikPayInWithoutCodeRequestDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: Information about the debited funds.
      title: CreateAblikPayInWithoutCodeRequestDebitedFunds
    TransactionStatus:
      type: string
      description: '**Returned values:** `CREATED`, `SUCCEEDED`, `FAILED`


        The status of the transaction.'
      title: TransactionStatus
    ResultMessage:
      type: string
      description: The explanation of the result code.
      title: ResultMessage
    FlowDescriptorResponse:
      type: object
      properties:
        FlowId:
          type: string
          description: Unique identifier of the payment flow, used by Mangopay for internal purposes.
        Beneficiaries:
          type:
          - array
          - 'null'
          items:
            $ref: '#/components/schemas/FlowDescriptorResponseBeneficiariesItems'
          description: 'Max. length: 5 items


            The list of up to 5 Natural or Legal Users declared as beneficiaries of the pay-in, who must all be KYC/KYB verified when the pay-in request is made. The pay-in also fails if the `Beneficiaries` array contains nulled objects or invalid `UserId` values.'
      description: "Information about the Owner beneficiaries targeted by the pay-in and its subsequent transfers, who must all be KYC/KYB verified when the pay-in request is made ([read more](/guides/payin-beneficiaries)).\n\nIf the `FlowDescriptor.Beneficiaries` is sent in the API request, then:\n- The transaction's `CreditedWalletId` holder is disregarded in KYC/KYB checks.\n- **ALL** `UserId` values in the array must be one of:\n  - `OWNER` whose `KYCLevel` is `REGULAR`\n  - `PLATFORM`\n  \nThe pay-in `Status` becomes `FAILED` with `ResultCode` [002951](/errors/codes/002951) if at least one `FlowDescriptor.Beneficiaries.UserId` is:\n- `PAYER`\n- `OWNER` whose `KYCLevel` is `LIGHT`\n\nIf the `FlowDescriptor.Beneficiaries` is not sent in the API request, then the `CreditedWalletId` holder is subject to KYC/KYB checks. This property is optional for backwards compatibility but is recommended for all pay-in flows, even when the `CreditedWalletId` holder is a `PAYER` or the same value as one of the `FlowDescriptor.Beneficiaries`.\n"
      title: FlowDescriptorResponse
    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
    CreateAblikPayInWithCodeRequestDebitedFunds:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: Information about the debited funds.
      title: CreateAblikPayInWithCodeRequestDebitedFunds
    IpAddress:
      type: string
      description: The IP address of the end user initiating the transaction, in IPV4 or IPV6 format.
      title: IpAddress
    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
    blik_create_blik_payin_Request:
      oneOf:
      - $ref: '#/components/schemas/CreateABLIKPayInWithCodeRequest'
      - $ref: '#/components/schemas/CreateABLIKPayInWithoutCodeRequest'
      title: blik_create_blik_payin_Request
    ReturnURL_255:
      type: string
      description: 'Max. length: 255 characters


        The URL to which the user is returned after the payment, whether the transaction is successful or not.'
      title: ReturnURL_255
    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
    CreateAblikPayInWithoutCodeRequestFees:
      type: object
      properties:
        Currency:
          $ref: '#/components/schemas/Currency_PLN'
        Amount:
          $ref: '#/components/schemas/Amount'
      required:
      - Currency
      - Amount
      description: Information about the fees.
      title: CreateAblikPayInWithoutCodeRequestFees
    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
    CreateABLIKPayInWithCodeRequest:
      type: object
      properties:
        AuthorId:
          $ref: '#/components/schemas/AuthorId'
        Tag:
          $ref: '#/components/schemas/Tag'
        CreditedWalletId:
          type: string
          description: The unique identifier of the credited wallet.
        FlowDescriptor:
          $ref: '#/components/schemas/FlowDescriptorRequest'
        DebitedFunds:
          $ref: '#/components/schemas/CreateAblikPayInWithCodeRequestDebitedFunds'
          description: Information about the debited funds.
        Fees:
          $ref: '#/components/schemas/CreateAblikPayInWithCodeRequestFees'
          description: Information about the fees.
        ReturnURL:
          $ref: '#/components/schemas/ReturnURL_255'
        StatementDescriptor:
          $ref: '#/components/schemas/StatementDescriptor'
        Code:
          type: string
          description: The 6-digit code from the user's banking application.
        BrowserInfo:
          $ref: '#/components/schemas/CreateAblikPayInWithCodeRequestBrowserInfo'
          description: Information about the browser used by the end user (author) to perform the payment.
        IpAddress:
          $ref: '#/components/schemas/IpAddress'
      required:
      - AuthorId
      - CreditedWalletId
      - DebitedFunds
      - Fees
      - Code
      - BrowserInfo
      - IpAddress
      description: BLIK pay-in request body including the code generated by the user in their app.
      title: CreateABLIKPayInWithCodeRequest
    Currency_PLN:
      type: string
      description: '**Allowed values:** `PLN`


        The currency of the amount.'
      title: Currency_PLN
    TransactionType:
      type: string
      description: '**Returned values:** `PAYIN`, `TRANSFER`, `CONVERSION`, `PAYOUT`


        The type of the transaction.'
      title: TransactionType
  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)