Mastercard

Mastercard Payment Requests API

The Payment Requests API from Mastercard — 4 operation(s) for payment requests.

Documentation GitHub OpenAPI

Operations 1

POST /payment-request-retrievals Mastercard Retrieve Payment Request Details. #

Work with this as data

Every API here is available over the APIs.io API and to AI agents over MCP.

MCP server

One button, every client — Claude, Cursor, VS Code and the rest.

https://apis.io/mcp

Tools for apis

7 MCP tools reach this

find_apisBrowse and filter every API in the catalog.
get_api_artifactsOne API's artifacts, grouped by type.
get_openapiThe primary OpenAPI for this API.
find_similar_apisAPIs that look like this one.
apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.
resolveTurn a domain, URL or GitHub org into the provider it belongs to.
find_cohortsEvery scored population of providers in the catalog.

All 92 tools →

Call it yourself

curl for this page

This API

curl "https://apis.io/api/v1/apis/mastercard-payment-requests-api"

All apis

curl "https://apis.io/api/v1/apis?limit=25"

Discovery needs no key. Ratings and market analysis are Pro.

Get an API key

Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.

GitHub Google LinkedIn

A second provider on the same verified email joins the account you already have.

OpenAPI Specification

openapi: 3.2.0
info:
  title: Mastercard Debtor Service Provider Resources Payment  Requests API
  description: Online checkouts can be frustrating and tedious. As shopping habits shift to digital, consumers and merchants require secure and streamlined online experiences. Mastercard Account to Account Commerce enables debtor service providers (DSP) to provide their debtors (customers) with a fast, secure, and convenient way to pay using their mobile banking app.= Through Account to Account Commerce, the debtors can view their balance before checkout, initiate refunds, and use their accounts for recurring payments or frequent purchases.
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/support
  version: 1.2.1
servers:
- url: https://mtf.services.mastercard.com/zapp/pbarfp/dsp
  description: Mastercard Test Facility (MTF) is a Production-like environment that enables DSP and Creditor Service Provider (CSP) to integrate and test end to end solution with Mastercard APIs.
- url: https://services.mastercard.com/zapp/pbarfp/dsp
  description: Production environment.
tags:
- name: Payment  Requests
paths:
  /payment-request-retrievals:
    post:
      tags:
      - Payment  Requests
      summary: Mastercard Retrieve Payment Request Details.
      description: Enables DSP to retrieve request for payment using either paymentRequestLifecycleId or paymentRequestReferenceNumber to present it to the debtor and obtain consent for funds transfer.
      operationId: retrievePaymentRequest
      parameters:
      - $ref: '#/components/parameters/X-Request-ID'
      - $ref: '#/components/parameters/X-Product-ID'
      - $ref: '#/components/parameters/X-Participant-ID'
      - $ref: '#/components/parameters/X-JWS-Signature'
      requestBody:
        $ref: '#/components/requestBodies/PaymentRequestDetailRetrievalRequest'
      responses:
        '200':
          $ref: '#/components/responses/PaymentRequestDetailRetrievalResponse'
        '400':
          $ref: '#/components/responses/BadRequestErrorResponse'
        '401':
          $ref: '#/components/responses/UnauthorisedErrorResponse'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    NewPaymentRequestDetailRetrieval:
      allOf:
      - $ref: '#/components/schemas/MessageRequestBlock'
      - type: object
        required:
        - transaction
        properties:
          transaction:
            $ref: '#/components/schemas/TransactionForPaymentRetrieval'
    PaymentRequestDetailRetrieval:
      allOf:
      - $ref: '#/components/schemas/MessageResponseBlock'
      - type: object
        required:
        - creditor
        - debtor
        - transaction
        properties:
          debtor:
            $ref: '#/components/schemas/DebtorAckForPaymentRetrieval'
          creditor:
            $ref: '#/components/schemas/CreditorAckForPaymentRetrieval'
          transaction:
            $ref: '#/components/schemas/TransactionAcknowledgement'
          agreementType:
            type: string
            example: AOF
            minLength: 1
            maxLength: 4
            description: Creditor requesting DSP to display to Debtor to setup Agreement during payment confirmation. * Refer to Codes and Formats section for more details.
    MessageRequestBlock:
      type: object
      required:
      - messageId
      - creationDateTime
      - initiatingPartyId
      - businessType
      properties:
        initiatingPartyId:
          type: string
          example: '000545'
          minLength: 1
          maxLength: 35
          description: Unique identifier of the message sender.
        messageId:
          type: string
          example: 7eab4eab35a542e085add0363a49c035
          minLength: 1
          maxLength: 35
          description: A point-to-point unique identifier is assigned to every message by the message initiator.
        creationDateTime:
          type: string
          example: '2020-11-20T06:57:24.465Z'
          format: date-time
          description: ISO 8601 format date and time in Coordinated Universal Time (UTC) when this message was created.
        businessType:
          type: number
          example: 3
          minimum: 1
          maximum: 999
          description: Unique identifier assigned by Mastercard to define the commercial product construct. * Refer to Codes and Formats section for more details.
    ErrorWrapper:
      description: A top level object for errors.
      type: object
      required:
      - Errors
      properties:
        Errors:
          $ref: '#/components/schemas/Errors'
    DebtorAckForPaymentRetrieval:
      type: object
      required:
      - debtorId
      - debtorServiceProviderId
      properties:
        debtorId:
          type: string
          example: Fxrsi5345
          minLength: 1
          maxLength: 35
          description: Unique identifier of the Debtor provided to Mastercard by the DSP.
        debtorServiceProviderId:
          type: string
          example: 000369
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned to the DSP during Mastercard onboarding.
    Error:
      description: A single error.
      type: object
      properties:
        Source:
          type: string
          example: ZAPP
          description: Source of the error.
        ReasonCode:
          type: string
          example: STVL-9999
          description: Error Code
        Description:
          type: string
          example: Invalid structure
          description: Error Description.
        Recoverable:
          type: boolean
          example: false
          description: Boolean value to specify if error is recoverable or not.
        Details:
          type: string
          example: Invalid structure
          description: Optional details of the error.
    Errors:
      description: Object that contains the list of errors.
      type: object
      required:
      - Error
      properties:
        Error:
          $ref: '#/components/schemas/ErrorList'
    ErrorList:
      description: The list of errors.
      type: array
      minItems: 1
      items:
        $ref: '#/components/schemas/Error'
    CreditorAckForPaymentRetrieval:
      type: object
      required:
      - creditorId
      - creditorServiceProviderId
      - creditorTradeName
      - creditorCategoryCode
      properties:
        creditorId:
          type: string
          example: VerizonoMobile000588
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned to the Creditor by the CSP.
        creditorServiceProviderId:
          type: string
          example: '000645'
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned to the CSP during Mastercard onboarding.
        creditorCategoryCode:
          type: string
          example: '0742'
          minLength: 4
          maxLength: 4
          description: The category code of the Creditor, also known as Merchant Category Code (MCC). Enables the classification of Creditors into specific categories based on the type of business, trade or services supplied.
        creditorTradeName:
          type: string
          example: VerizonoMobileLtd
          minLength: 1
          maxLength: 35
          description: Name used by the Creditor in dealing with customers, which may not be the same as the one it uses for legal purposes.
        creditorReturnString:
          type: string
          example: https://www.creditor.com/creditorreturnstring
          minLength: 1
          maxLength: 512
          description: Return string (in URL encoded format) that is passed to the DSP to return the Debtor back to the Creditor's page.
        creditorLogoUrl:
          type: string
          example: https://www.cdn.com/creditorlogourl
          minLength: 1
          maxLength: 512
          description: Creditor's Logo (in URL encoded format). Can be used by the Debtor to display the Creditor's Logo.
        creditorAccount:
          type: object
          required:
          - accountNumber
          description: Creditor's Account Information. Either the IBAN or account number should be used. This is provided only for Me-to-Me payments.
          properties:
            accountNumber:
              type: string
              x-guarded-string: 'true'
              example: '45122351223323'
              minLength: 1
              maxLength: 35
              description: Unique identifier for each account assigned by a financial institution or wallet provider. For example, IBAN. If sort code or routing number is 451223 and account number is 51223323, then after concatenation, the account number will be 45122351223323.
            clearingSystem:
              type: string
              example: FPS
              minLength: 1
              maxLength: 35
              description: Creditor or CSP requested real-time settlement method. * Refer to Codes and Formats section for more details.
          example: example_value
        creditorAccounts:
          type: array
          deprecated: true
          description: Creditor's Account Information. Either of the IBAN or Other account should be used. (This "creditorAccounts" block is deprecated, use "creditorAccount" block)
          items:
            type: object
            properties:
              iban:
                type: string
                x-guarded-string: 'true'
                example: GB54HBUK60161331926819
                minLength: 1
                maxLength: 35
                description: International Bank Account Number to uniquely identify the account.
              other:
                type: object
                description: Unique identification of an account.
                required:
                - accountNumber
                properties:
                  accountNumber:
                    type: string
                    x-guarded-string: 'true'
                    example: '45122351223323'
                    minLength: 1
                    maxLength: 35
                    description: Unique Identifier for each account assigned by a financial institution. For example, if sort code or routing number is 451223 and account number is 51223323, then after concatenation the account number will be 45122351223323.
              clearingSystems:
                type: array
                items:
                  type: string
                example:
                - FPS
                description: Creditor or CSP requested real-time settlement method. * Refer to Codes and Formats section for more details.
          example: []
    TransactionAcknowledgement:
      type: object
      required:
      - endToEndId
      - instructedAmount
      - paymentRequestLifecycleId
      - categoryPurpose
      - confirmationExpiryTimeInterval
      - paymentRequestType
      - instructionId
      - transactionCreationDateTime
      - purpose
      properties:
        paymentRequestLifecycleId:
          type: string
          example: '923123123123123100'
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services.
        endToEndId:
          type: string
          example: 7jhg5eab35a542e085add0363a4423o6
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned by Creditor to identify Payment Request in their system.
        instructionId:
          type: string
          example: 98dj4eab35a542e085add0363a40jk564
          minLength: 1
          maxLength: 60
          description: Unique identifier for the transaction assigned by the transaction initiator (CSP).
        accountServicerReference:
          type: string
          example: '12254935976349875'
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned by Mastercard, to identify a particular payment (also referred to as settlement identifier) associated with a Payment Request.
        reconId:
          type: string
          example: RECON1201202201
          minLength: 1
          maxLength: 15
          description: Reconciliation identifier assigned by Mastercard to the transaction.
        confirmationExpiryTimeInterval:
          type: number
          example: 150
          description: Time window given in seconds within which the Payment Confirmation must be received by the Mastercard.
        paymentRequestType:
          type: string
          example: IMDT
          minLength: 4
          maxLength: 4
          description: Set by the Creditor/CSP to define the settlement type of the Payment Request. * Refer to Codes and Formats section for more details.
        transactionCreationDateTime:
          type: string
          format: date-time
          example: '2020-11-20T06:57:24.465Z'
          description: ISO 8601 format date and time in Coordinated Universal Time (UTC) the Payment Request was created.
        instructedAmount:
          description: The total amount of the payment request, as specified by the Creditor.
          allOf:
          - $ref: '#/components/schemas/Amount'
          example: example_value
        purpose:
          type: string
          example: ONLN
          minLength: 1
          maxLength: 35
          description: Set by Creditor/CSP to indicate the Payment Request type. * Refer to Codes and Formats section for more details.
        categoryPurpose:
          type: string
          example: PYMT
          minLength: 1
          maxLength: 35
          description: Set by the Creditor/CSP to offer specific transaction processing. * Refer to Codes and Formats section for more details.
        restriction:
          type: string
          example: 18PLUS
          minLength: 1
          maxLength: 30
          description: Set by the Creditor/CSP to communicate any restrictions to be verified by DSP before payment authorization. * Refer to Codes and Formats section for more details.
        creditAccountAllowed:
          type: boolean
          example: true
          description: Indicator to specify Credit account can be used for the payment.
        strongCustomerAuthentication:
          type: boolean
          example: true
          description: Indicates a request from Creditor to DSP to step-up authentication for the transaction.
    MessageResponseBlock:
      type: object
      required:
      - messageId
      - creationDateTime
      - initiatingPartyId
      - originalMessageId
      properties:
        initiatingPartyId:
          type: string
          example: ZAPP
          minLength: 1
          maxLength: 35
          description: Unique identifier of the message sender.
        messageId:
          type: string
          example: 3bef00e542ec4be583b1b5d449799084
          minLength: 1
          maxLength: 35
          description: A point-to-point unique identifier is assigned to every message by the message initiator.
        creationDateTime:
          type: string
          example: '2020-11-20T06:57:24.465Z'
          format: date-time
          description: ISO 8601 format date and time in Coordinated Universal Time (UTC) when this message was created.
        originalMessageId:
          type: string
          example: 7eab4eab35a542e085add0363a49c035
          minLength: 1
          maxLength: 35
          description: Original message identifier generated and sent by the initiator of the request message.
    TransactionForPaymentRetrieval:
      type: object
      required:
      - debtorServiceProviderId
      - debtorId
      - retrieveInitMethod
      properties:
        paymentRequestLifecycleId:
          type: string
          example: '923123123123123100'
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned by Mastercard, to identify the payment request in subsequent transactions or services.
        debtorId:
          type: string
          example: Fxrsi5345
          minLength: 1
          maxLength: 35
          description: Unique identifier of the Debtor provided to Mastercard by the DSP.
        debtorServiceProviderId:
          type: string
          example: 000369
          minLength: 1
          maxLength: 35
          description: Unique identifier assigned to the DSP during Mastercard onboarding.
        retrieveInitMethod:
          type: string
          example: INTENT
          minLength: 1
          maxLength: 30
          description: Set by DSP to specify Payment Request retrieval initiation method. * Refer to Codes and Formats section for more details.
        paymentRequestReferenceNumber:
          type: string
          example: '789563'
          minLength: 6
          maxLength: 6
          description: Unique 6 character reference provided by Mastercard to the CSP to be conveyed to the Debtor to make a payment.
    Amount:
      required:
      - currency
      - value
      type: object
      properties:
        currency:
          type: string
          example: GBP
          maxLength: 3
          minLength: 3
          description: ISO 4217 code for Currency.
        value:
          type: number
          example: 100.25
          description: Amount value.
  headers:
    X-Product-ID:
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: PBARFP
      description: Unique identifier assigned to the product by Mastercard and given to the participant.
    X-JWS-Signature:
      required: true
      description: JWS detached signature is applied to ensure data integrity.
      schema:
        type: string
        example: eyJhbGciOiJSUzI1NiIsImtpZCI6Ik1LMGlrb1k3NFpNdUhnbncwSG1MNnpSbi9rRT0iLCJpYXQiOiIxNjc1OTYyMjA3IiwiY3JpdCI6WyJpYXQiXX0..XRHc_Q7mp49sr0CDL6Ps97uz4Lhl3XG_--JfeZrkj-4LK-3gzc7HsN0Jq4UjO_NX5ZlVp_tfL_GE1g9-vUT0NCfXmfbBXYEaC9CgFZIoU9F2PBegdZwHHmkDbu-5-t6kd2xo4UhaQ5VP1quWOD5yAs2a6MlQstT1iT-gPIW1teaiz4lgCmqbcTo6umjLKL-QsYvJ53Ngtb5rrF5WWQ1WKpGeq_PP1hGYbxDzcYBNZqGed-dXuGqpkWJ85JENJyOKDoskWM6cgs6OAjrmjTIFQ0qdfal91SUQtzJ49nbAiqMpROh79uYJ024jgtcQ_StqYJyJWYdLeUv1ge-kDJN0fw
        minLength: 1
        maxLength: 512
    X-Participant-ID:
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: '000545'
      description: Unique identifier assigned to the participant by Mastercard during onboarding.
    X-Request-ID:
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: 7eab4eab35a542e085add0363a49c035
      description: Each API request has an associated request identifier. It can be used to match the response to the request and for tracing, troubleshooting and analysis purposes.
  examples:
    BadRequestErrorExample:
      value:
        Errors:
          Error:
          - Source: ZAPP
            ReasonCode: STVL-9999
            Description: Invalid structure.
            Recoverable: false
            Details: Invalid structure
    UnauthorisedExample:
      value:
        Errors:
          Error:
          - Source: ZAPP
            ReasonCode: SECU-9999
            Description: Invalid signature.
            Recoverable: false
            Details: Invalid signature
  parameters:
    X-Participant-ID:
      name: X-Participant-ID
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: '000545'
      description: Unique identifier assigned to the participant by Mastercard during onboarding.
    X-Request-ID:
      name: X-Request-ID
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: 7eab4eab35a542e085add0363a49c035
      description: Each API request has an associated request identifier. It can be used to match the response to the request and used for tracing, troubleshooting and analysis purposes.
    X-Product-ID:
      name: X-Product-ID
      in: header
      required: true
      schema:
        type: string
        minLength: 1
        maxLength: 50
        example: PBARFP
      description: Unique identifier assigned to the product by Mastercard and given to the participant.
    X-JWS-Signature:
      name: X-JWS-Signature
      in: header
      required: true
      description: JWS detached signature is applied to ensure data integrity.
      schema:
        type: string
        example: eyJhbGciOiJSUzI1NiIsImtpZCI6Ik1LMGlrb1k3NFpNdUhnbncwSG1MNnpSbi9rRT0iLCJpYXQiOiIxNjc1OTYyMjA3IiwiY3JpdCI6WyJpYXQiXX0..XRHc_Q7mp49sr0CDL6Ps97uz4Lhl3XG_--JfeZrkj-4LK-3gzc7HsN0Jq4UjO_NX5ZlVp_tfL_GE1g9-vUT0NCfXmfbBXYEaC9CgFZIoU9F2PBegdZwHHmkDbu-5-t6kd2xo4UhaQ5VP1quWOD5yAs2a6MlQstT1iT-gPIW1teaiz4lgCmqbcTo6umjLKL-QsYvJ53Ngtb5rrF5WWQ1WKpGeq_PP1hGYbxDzcYBNZqGed-dXuGqpkWJ85JENJyOKDoskWM6cgs6OAjrmjTIFQ0qdfal91SUQtzJ49nbAiqMpROh79uYJ024jgtcQ_StqYJyJWYdLeUv1ge-kDJN0fw
        minLength: 1
        maxLength: 512
  requestBodies:
    PaymentRequestDetailRetrievalRequest:
      required: true
      description: Retrieve Payment Request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/NewPaymentRequestDetailRetrieval'
  responses:
    BadRequestErrorResponse:
      description: 'Invalid structure: The header or payload fails syntax or structural validation.'
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Product-ID:
          $ref: '#/components/headers/X-Product-ID'
        X-Participant-ID:
          $ref: '#/components/headers/X-Participant-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestErrorExample:
              $ref: '#/components/examples/BadRequestErrorExample'
    UnauthorisedErrorResponse:
      description: Invalid signature. The service fails signature validation.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Product-ID:
          $ref: '#/components/headers/X-Product-ID'
        X-Participant-ID:
          $ref: '#/components/headers/X-Participant-ID'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorWrapper'
          examples:
            BadRequestExample:
              $ref: '#/components/examples/UnauthorisedExample'
    PaymentRequestDetailRetrievalResponse:
      description: Payment Request creation successful.
      headers:
        X-Request-ID:
          $ref: '#/components/headers/X-Request-ID'
        X-Product-ID:
          $ref: '#/components/headers/X-Product-ID'
        X-Participant-ID:
          $ref: '#/components/headers/X-Participant-ID'
        X-JWS-Signature:
          $ref: '#/components/headers/X-JWS-Signature'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/PaymentRequestDetailRetrieval'

Mastercard Payment Requests API

Operations 1

Documentation

Specifications

Code Examples

Other Resources