Every API here is available over the APIs.io API and to AI agents over MCP.
---
openapi: 3.0.0
info:
description: >
Merchant Presented QR is a Service that includes payment or
transactions process with tokens.
A Registered Merchant on the service can expose a QR in the store, and the
users of an Issuer´s Tokenized Wallet can read the QR Code and introduce the
payment information. This system includes the process of generating the QR
Token for merchants, Reading that QR and making payment with token.
**Interactions**
- Issuer’s Wallet
Interactions from Issuer’s Wallet is going to be with our SDK.
Please refer to SDK Documentation for details.
- Acquirer Platform
Interactions with Acquirer are along with APIs and include other mechanisms
to interact with ISO transactions.
**Benefits for Acquirers and Merchants**
NovoPayment MPQR manages the interaction with the card schemes for you and
allows you to focus on the core of your business, freeing you from the
effort of interconnection with each merchant and wallet and allowing your
customers to quickly access the benefits of using a QR how method to
initiate a payment transaction.
version: v1
title: Merchant Presented QR
servers:
- description: Sandbox
url: https://sandbox-api.novopayment.com/api/v1/mpqr
paths:
/onboarding:
post:
summary: Create Merchant
description: Acquirers use this endpoint to register a Merchant in the MPQR ecosystem
operationId: CreateMerchant
requestBody:
$ref: "#/components/requestBodies/RQCreateMerchant"
responses:
"200":
$ref: "#/components/responses/RSCreateMerchant"
"400":
$ref: "#/components/responses/RSCreateMerchant400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
/generateqr:
post:
summary: Generate QR Code
description: Acquirers use this endpoint to register a Merchant in the MPQR ecosystem
operationId: GenerateQRCode
parameters:
- $ref: "#/components/parameters/XRequestId"
- $ref: "#/components/parameters/XPayToken"
- $ref: "#/components/parameters/XTenantId"
- $ref: "#/components/parameters/Accept"
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/createApiKey"
requestBody:
$ref: "#/components/requestBodies/RQGenerateQrCode"
responses:
"200":
$ref: "#/components/responses/RSGenerateQrCode"
"400":
$ref: "#/components/responses/RSGenerateQrCode400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
/decoderqr:
post:
summary: Decoder QR code
operationId: DecoderQRCode
parameters:
- $ref: "#/components/parameters/XRequestId"
- $ref: "#/components/parameters/XPayToken"
- $ref: "#/components/parameters/XTenantId"
- $ref: "#/components/parameters/Accept"
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/createApiKey"
requestBody:
$ref: "#/components/requestBodies/RQDecoderQrCode"
responses:
"201":
$ref: "#/components/responses/RSDecoderQR"
"400":
$ref: "#/components/responses/RSGenerateQrCode400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
/sendpayment:
post:
summary: Send data of payment.
operationId: sendPayment
parameters:
- $ref: "#/components/parameters/XRequestId"
- $ref: "#/components/parameters/XPayToken"
- $ref: "#/components/parameters/XTenantId"
- $ref: "#/components/parameters/Accept"
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/createApiKey"
requestBody:
$ref: "#/components/requestBodies/RQSendPayment"
responses:
"201":
$ref: "#/components/responses/RSSendPayment"
"400":
$ref: "#/components/responses/RSGenerateQrCode400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
/transaction/makepayment:
post:
summary: Make a payment.
operationId: makePayment
parameters:
- $ref: "#/components/parameters/XRequestId"
- $ref: "#/components/parameters/XPayToken"
- $ref: "#/components/parameters/XTenantId"
- $ref: "#/components/parameters/Accept"
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/createApiKey"
requestBody:
$ref: "#/components/requestBodies/RQMakePayment"
responses:
"201":
$ref: "#/components/responses/RSMakePayment"
"400":
$ref: "#/components/responses/RSGenerateQrCode400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
/notifications/payment:
post:
summary: Notify status for a payment.
operationId: notificationsPayment
parameters:
- $ref: "#/components/parameters/XRequestId"
- $ref: "#/components/parameters/XPayToken"
- $ref: "#/components/parameters/XTenantId"
- $ref: "#/components/parameters/Accept"
- $ref: "#/components/parameters/apikey"
- $ref: "#/components/parameters/createApiKey"
requestBody:
$ref: "#/components/requestBodies/RQNotificationPayment"
responses:
"201":
$ref: "#/components/responses/RSNotificationPayment"
"400":
$ref: "#/components/responses/RSGenerateQrCode400"
"401":
$ref: "#/components/responses/RS401"
"500":
$ref: "#/components/responses/RS500"
security:
- oAuth2ClientCredentials: []
components:
securitySchemes:
oAuth2ClientCredentials:
type: oauth2
description: >
See [Oauth2
API](https://developer.novopayment.com/api/authentication-method-and-encryption/oauth2-api)
flows:
clientCredentials:
tokenUrl: https://sandbox-api.novopayment.com/oauth2/token
scopes: {}
parameters:
transactionId:
name: transactionId
in: path
description: Unique transaction ID
required: true
schema:
type: string
maxLength: 38
transferId:
name: transferId
in: path
description: Unique transfer Identifier
required: true
schema:
type: string
maxLength: 38
apikey:
name: apikey
in: query
description: Public API key, which is different from the shared secret.
required: true
schema:
type: string
maxLength: 49
createApiKey:
name: createApiKey
in: query
description: |
Whether to create a new API key for the client.
Note: do not set to true.
required: true
schema:
type: string
enum:
- false
- true
XRequestId:
name: x-request-id
in: header
description: |
Unique ID for the API request.
Format: Alphabetic, numeric, and hyphens ( - ), e.g. spaces are not allowed.
required: true
schema:
type: string
maxLength: 36
XPayToken:
name: x-pay-token
in: header
description: |
A token identifying the transaction and its contents.
The token expires in 480 seconds (8 minutes) for all clients.
required: true
schema:
type: string
Accept:
name: Accept
in: header
description: |
Acceptable response format.
Format: Must include application/json
required: true
schema:
type: string
XTenantId:
name: X-tenant-id
in: header
description: |
It is necessary send all petitions for identified the client.
required: true
schema:
type: string
examples:
NoResultsFound:
value:
code: 200.22.364
message: No results found
datetime: "2020-01-03T16:05:56.517Z"
data:
status: 401
code: 9159
severity: ERROR
message: TokenValidationFailed
info: ""
CreateMerchantOk:
value:
code: 200.22.000
message: Process Ok
datetime: "2020-01-03T16:05:56.517Z"
data:
id: 8e9ed12e-e4ba-4ad2-ac9d-2bcb1c8fc18a
acquirerIdentifiers:
acquirerId: 66978068
acquirerMerchantId: 9655936598
tokenizationConfiguration:
channelSecurityContext: SHARED_SECRET
tokenizationProfiles:
profileName: Test1
applicationId: Test1
tokenRequestorId: 40000000057
qrData: iVB...YII=
ParamsRequired:
value:
code: 400.22.003
message: Params required
datetime: "2020-01-03T16:05:56.517Z"
InvalidTenantId:
value:
code: 400.22.004
message: Invalid Tenant ID
datetime: "2020-01-03T16:05:56.517Z"
InvalidData:
value:
code: 400.22.089
message: Invalid Data
datetime: "2020-01-03T16:05:56.517Z"
InvalidParameters:
value:
code: 400.22.396
message: Invalid Parameters
datetime: "2020-01-03T16:05:56.517Z"
ErrorGeneralServices:
value:
code: 400.22.350
message: Error General Services
datetime: "2020-01-03T16:05:56.517Z"
InternalServerError:
value:
code: 500.22.999
message: Internal Server Error
datetime: "2020-01-03T16:05:56.517Z"
InvalidAccessToken:
value:
code: 401.22.990
message: Invalid Access Token
datetime: "2020-01-03T16:05:56.517Z"
AccessTokenNotApproved:
value:
code: 401.22.991
message: Access Token not approved
datetime: "2020-01-03T16:05:56.517Z"
InvalidSignature:
value:
code: 401.22.992
message: Invalid signature
datetime: "2020-01-03T16:05:56.517Z"
AccessTokenExpired:
value:
code: 401.22.993
message: Access token expired
datetime: "2020-01-03T16:05:56.517Z"
schemas:
RQCreateMerchant:
type: object
required:
- companyPrimaryLegalName
- primaryWebsiteURL
- companyCity
- companyCountryCode
- primaryContactEmail
- acquirerIdentifiers
properties:
serviceContext:
type: string
description: Service context
example: TOKENIZATION
maxLength: 13
enum:
- TOKENIZATION
dunsNumber:
type: number
description: A D&B DUNS number is a nine-digit number that is recognized as the
universal standard to track businesses worldwide. It is designed to
enhance the credibility of your business and enable potential
customers, lenders, and suppliers to learn about your company.
example: 75102765
maxLength: 9
companyPrimaryTradeName:
type: string
description: Trade name of token requestor, such as a doing-business-as(DBA)
name. If not specified, the legal name(companyPrimaryLegalName) is
used by default.<br><br>**Allowed characters**:<br>Alphanumeric,
excepting semi-colon, percent sign, and parentheses.
maxLength: 75
companyPrimaryLegalName:
type: string
description: Legal name of token requestor. Some processors may not support a
75-character legal name. You cannot exceed the limit imposed by your
processor.<br><br>**Allowed characters**:<br>Alphanumeric, excepting
semi-colon, percent sign, and parentheses
example: Pepito Pizza
maxLength: 75
status:
type: string
primaryWebsiteURL:
type: string
description: The URL for your token requestor’s site for handling VTS
transactions.<br><br>**Allowed characters**:<br>Alphanumeric, valid
URL
example: www.pepitospizza.com
maxLength: 100
companyAddress1:
type: string
description: >
First line of the token Requestor’s primary
address.<br><br>**Allowed characters**:<br>Alphabetic, numeric, or
the following characters: spaces, ‘ (single quote), # (pound-sign or
hash), , (comma), _ (underscore), :(colon), / (forward slash), and –
(hyphen)
maxLength: 140
companyAddress2:
type: string
description: >
First line of the token requestor’s primary
address.<br><br>**Allowed characters**: Alphabetic, numeric, or the
following characters: spaces, ‘ (single quote), # (pound-sign or
hash), , (comma), _ (underscore), :(colon), / (forward slash), and –
(hyphen)
maxLength: 140
companyCity:
type: string
description: >
City in the token requestor’s primary address.<br><br>**Allowed
characters**:<br>Alphabetic, numeric, or the following characters:
spaces, ‘ (single quote), . (period), and – (hyphen)
example: Mexico City
maxLength: 100
companyStateProvinceCode:
type: string
description: State or province code associated with the physical address in the
specified country. The companyStateProvinceCode for US must be a
standard 2-characters code.
maxLength: 2
companyPostalCode:
type: string
description: Postal code associated with the primary address of token requestor,
such as a ZIP code.
maxLength: 7
companyCountryCode:
type: string
description: ISO-3166-1 alpha-2 standard country associated with the token
requestor’s primary address.
example: MX
maxLength: 2
companyPhone:
type: string
description: Token requestor’s primary phone number.
maxLength: 16
primaryContactFirstName:
type: string
description: First name of token requestor’s primary contact person.
maxLength: 256
primaryContactLastName:
type: string
description: >
Surname of token requestor’s primary contact
person.<br><br>**Allowed characters**:<br>Alphabetic or the
following characters: spaces, ‘ (single quote), ` (back tick), ~
(tilde), “ (double quote), . (period), and – (hyphen)
maxLength: 256
primaryContactEmail:
type: string
description: Email address of token requestor’s primary contact.
example: ventas@pepitospizza.com
maxLength: 256
relationships:
type: object
description: >
Relationship to the token requestor being onboarded, which is by
externalClientId. If not specified, Visa creates the
externalClientId for you, which is available in the
response.<br><br>**Allowed characters**:<br>An array of
Relationships structures.
properties:
externalClientId:
type: string
description: >
The relationship ID for the entity being onboarded. This is the
relationship ID to use when calling TSP APIs.
maxLength: 100
acquirerIdentifiers:
type: object
description: Acquirer and merchant identifiers
required:
- acquirerId
- acquirerMerchantId
properties:
acquirerId:
type: string
description: >
Acquirer Id
example: 66978068
maxLength: 15
acquirerMerchantId:
type: string
description: >
Unique identifier relation Acquirer and Merchant Id.<br><br>This
value is mandatory in future request.
example: 9655936598
maxLength: 25
tokenizationConfiguration:
type: object
required:
- tokenizationProfiles
- tokenRequestorId
properties:
channelSecurityContext:
type: string
description: >
Channel security context; default is shared secret.
maxLength: 100
tokenizationProfiles:
type: object
description: >
List of profiles
required:
- profileName
- applicationId
properties:
profileName:
type: string
description: >
Profile name in tokenization services
maxLength: 50
applicationId:
type: string
description: >
Unique Identifier same as the wallet provider
maxLength: 36
tokenRequestorId:
type: string
description: >
Identification to use for payments
maxLength: 20
RSCreateMerchant:
type: object
properties:
code:
type: string
example: 200.22.000
description: Operation response code
maxLength: 10
message:
type: string
example: Process Ok
description: Response code description
maxLength: 140
datetime:
type: string
example: "2020-01-03T16:05:56.517Z"
description: Operation Time Stamp in ISO 8601 format
format: date-time
data:
type: object
properties:
id:
type: string
description: >
VISA's identification response Id
acquirerIdentifiers:
type: object
required:
- acquirerId
- acquirerMerchantId
properties:
acquirerId:
type: string
description: >
Acquirer ID
acquirerMerchantId:
type: string
description: >
Unique identifier relation Acquirer and Merchant Id
tokenizationConfiguration:
type: object
required:
- tokenizationProfiles
- tokenRequestorId
properties:
channelSecurityContext:
type: string
description: >
Channel security context; default is shared secret.
maxLength: 100
tokenizationProfiles:
type: object
description: >
List of profiles
required:
- profileName
- applicationId
properties:
profileName:
type: string
description: >
Profile name in tokenization services
maxLength: 50
applicationId:
type: string
description: >
Unique Identifier same as the wallet provider
maxLength: 36
tokenRequestorId:
type: string
description: >
Identification to use for payments
maxLength: 20
qrData:
type: string
description: >
Raw entire QR code data, from scanning QR. Base64 encoded
RSCreateMerchant400:
type: object
properties:
code:
type: string
example: 400.22.003
description: Operation response code
minLength: 10
maxLength: 10
message:
type: string
example: Params required
description: Response code description
maxLength: 140
datetime:
type: string
example: "2020-01-03T16:05:56.517Z"
format: date-time
RQGenerateQrCode:
type: object
required:
- merchantId
- acquirerId
- pointOfInitiationMethod
- merchantCategoryCode
- transactionCurrency
- transactionAmount
- tipOrConvenienceIndicator
- countryCode
- merchantName
- merchantCity
properties:
merchantId:
type: string
description: Identification of the merchant in Novo's system
example: 75102765
maxLength: 25
acquirerId:
type: string
description: Identification of the acquirer registered in Novo's system
maxLength: 15
merchantAccountInformation:
type: string
description: Account Information of Merchant
example: "4156821587554841"
payloadFormatIndicator:
type: string
pointOfInitiationMethod:
type: string
description: Identifies the communication technology (here QR Code) and whether
the data is static or dynamic
example: 12
maxLength: 2
merchantCategoryCode:
type: string
description: As defined by [ISO 18245] and assigned by the Acquirer
example: 4111
maxLength: 100
transactionCurrency:
type: string
description: Indicates the currency code of the transaction. A 3-digit numeric
value, as defined by [ISO 4217]. This value will be used by the
mobile application to display a recognizable currency to the
consumer whenever an amount is being displayed or whenever the
consumer is prompted to enter an amount.
example: 156
maxLength: 3
transactionAmount:
type: string
description: The transaction amount (excluding tips and convenience fees), if
known. For instance, "99.34". If present, this value is displayed to
the consumer by the mobile application when processing the
transaction. If this data object is not present, the consumer is
prompted to input the transaction amount to be paid to the merchant.
example: 237200
maxLength: 50
tipOrConvenienceIndicator:
type: string
description: Indicates whether the consumer will be prompted to enter a tip or
whether the merchant has determined that a flat, or percentage
convenience fee is charged.
example: 1
maxLength: 100
countryCode:
type: string
description: Indicates the country of the merchant acceptance device. A
2-character alpha value, as defined by [ISO 3166-1 alpha 2] and
assigned by the Acquirer. The country may be displayed to the
consumer by the mobile application when processing the transaction.
example: CO
maxLength: 10
merchantName:
type: string
description: The "doing business as" name for the merchant, recognizable to the
consumer. This name may be displayed to the consumer by the mobile
application when processing the transaction.
example: Pizzería Pepito
maxLength: 100
merchantCity:
type: string
description: City of operations for the merchant. This name may be displayed to
the consumer by the mobile application when processing the
transaction.
example: MANIZALES
maxLength: 100
additionalDataField:
type: object
description: Additional Information
properties:
billNumber:
type: string
description: >
The invoice number or bill number. This number can be provided by
the merchant or can be an indicator for the mobile application
to prompt the consumer to input a Bill Number. For example, the
Bill Number may be present when the QR Code is used for bill
payment.
mobileNumber:
type: string
description: >
The mobile number can be provided by the merchant or can be an
indicator for the mobile application to prompt the consumer to
input a Mobile Number. For example, the Mobile Number to be used
for multiple use cases, such as mobile top-up and bill payment.
storeLabel:
type: string
description: >
A distinctive value associated to a store. This value can be
provided by the merchant or can be an indication for the mobile
application to prompt the consumer to input a Store Label.
example: 1234
loyaltyNumber:
type: string
description: >
Typically, a loyalty card number. This number can be provided by
the merchant, if known, or can be an indication for the mobile
application to prompt the consumer to input their Loyalty
Number.
referenceLabel:
type: string
description: >
Any value as defined by the merchant or acquirer in order to
identify the transaction. This value can be provided by the
merchant or can be an indication for the mobile app to prompt
the consumer to input a transaction Reference Label. For
example, the Reference Label may be used by the consumer mobile
application for transaction logging or receipt display.
customerLabel:
type: string
description: >
Any value identifying a specific consumer. This value can be
provided by the merchant (if known), or can be an indication for
the mobile application to prompt the consumer to input their
Customer Label. For example, the Customer Label may be a
subscriber ID for subscription services, a student enrolment
number, etc.
example: "***"
terminalLabel:
type: string
description: >
A distinctive value associated to a terminal in the store. This
value can be provided by the merchant or can be an indication
for the mobile application to prompt the consumer to input a
Terminal Label. For example, the Terminal Label may be displayed
to the consumer on the mobile application identifying a specific
terminal.
example: A6008667
purposeTransaction:
type: string
description: >
Any value defining the purpose of the transaction. This value can
be provided by the merchant or can be an indication for the
mobile application to prompt the consumer to input a value
describing the purpose of the transaction. For example, the
Purpose of Transaction may have the value "International Data
Package" for display on the mobile application.
additionalConsumerDataRequest:
type: string
description: >
Contains indications that the mobile application is to provide the
requested information in order to complete the transaction. The
information requested should be provided by the mobile
application in the authorization without unnecessarily prompting
the consumer. For example, the Additional Consumer Data Request
may indicate that the consumer mobile number is required to
complete the transaction, in which case the mobile application
should be able to provide this number (that the mobile
application has previously stored) without unnecessarily
prompting the consumer.
example: ME
sizeQR:
type: string
description: |
Size in pixels for the QR Code Generate.
**Available Values:**
A – 200 x 200
B – 400 x 400
C – 600 x 600
**Default values is B**
maxLength: 1
enum:
- A
- B
- C
RQDecoderQrCode:
type: object
required:
- qrEncodeData
properties:
qrEncodeData:
type: string
description: QR code in string format.
example: 00020101021203114000000005752044111530315654062372005502015802CO5915Compania NOVO 36006BOGOTA62630102''0202''030412340402''0502''0603***0708A60086670802''0902ME6304EAAC
RQSendPayment:
type: object
required:
- srciTransactionId
- srcClientId
- serviceId
properties:
srcCorrelationId:
type: string
description: The unique identifier generated by Visa to track and link API
messages. This is used as a transaction identifier assigned by Visa
for this particular transaction. Universally Unique Identifier (UUID).
example: 5821c929-deee-49b7-a6ce-ba88dadbb734
srciTransactionId:
type: string
description: Transaction ID.
example: 2f679779-3f42-4b8e-5e81-1d259e56ber1
srcDigitalCardId:
type: string
description: Digital Card ID.
example: ffdbfe5575be88bc64ee175a907c3e02
serviceId:
type: string
description: Form of payment service. In case of Visa QR, value is SELLER_PRESENTED.
example: SELLER_PRESENTED
enum:
- SELLER_PRESENTED
srcDpaId:
type: string
description: DPA ID.
example: NA
srcClientId:
type: string
description: Identifies the connecting client, e.g. Mobile
Application Provider, Payment Enabler, etc.
This field should contain the API Key of the Wallet Provider.
example: "XGIS3U97PK6ZLPNEOTIX212erG6IZbDUcd2OfQIKK1-YPbbRM"
dpaData:
type: object
$ref: "#/components/schemas/ObjDpaData"
dpaTransactionOptions:
type: object
$ref: "#/components/schemas/ObjDpaTransactionOptions"
srcInitiatorId:
type: string
description: Client ID of the Token Requestor. Format UUID.
example: fa3cf6c8-2c4a-991f-03ef-193e03800601
clientAppID:
type: string
description: Client APP ID of the TR (wallet) profile. This is the information that TR-TSP submitted for the TR (wallet)
during onboarding. Required in case of TR-TSP calling checkout on behalf of the TR (wallet).
ObjAssuranceData:
type: object
properties:
cardVerificationEntity:
type: string
cardVerificationMethod:
type: string
cardVerificationResults:
type: string
cardVerificationTimestamp:
type: string
cardAssuranceData:
type: string
cardholderAuthenticationEntity:
type: string
cardholderAuthenticationMethod:
type: string
cardholderAuthenticationResults:
type: string
cardholderAuthenticationTimestamp:
type: string
cardholderAssuranceData:
type: string
consumerVerificationEntity:
type: string
consumerVerificationMethod:
type: string
consumerVerificationResults:
type: string
consumerVerificationTimestamp:
type: string
# --- truncated at 32 KB (77 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/novopayment/refs/heads/main/openapi/novopayment-merchant-presented-qr-openapi.yml