Payment21® Crypto API 1.26
The purpose of this document is to describe the requirements, usage, implementation and purpose of the Payment21® Application Programming Interface (API). The API will allow merchants to send payment requests through a consistently available online interface, which can integrate well with any of their existing systems.
Version
Last updated | 04.05.2020 |
Version No | 1.26 |
Owner | Moving Media GmbH |
Document Name | Payment21_Crypto_JSON_REST_API |
Revision History
Date | Description | Initials | Version |
---|---|---|---|
25.02.16 | Rename required confirmations to delivery level | GS | 1.09 |
24.03.16 | Editorial Update | CH | 1.10 |
02.05.16 | Update for clarification | VB | 1.11 |
03.05.16 | Adding Bitcoin Testnet and updating various items | BK | 1.12 |
19.05.16 | Adding PUT, GET, PATCH | RM | 1.13 |
25.08.16 | Update usage of delivery level | PI | 1.14 |
09.09.16 | Documenting minumum order amount | PI | 1.15 |
07.10.16 | Update the sandbox test and payment page | PI | 1.16 |
19.10.16 | Add business address to vendor requests | PI | 1.17 |
31.10.16 | Improve description for response error codes | PI | 1.18 |
20.12.16 | Add disbursement documentation (i.e. payout) | PI | 1.19 |
30.01.17 | Add more error codes to the API | PI | 1.20 |
15.02.17 | Improve integration steps | PI | 1.21 |
27.10.17 | Update p21PayByCrypto API | PI | 1.22 |
17.05.18 | Add Payout Page, E-Billing, Payment Button and OTC Exchange details | DR | 1.23 |
08.03.19 | Update payout flow | PI | 1.24 |
15.07.19 | Add off-chain payments | PI | 1.25 |
04.05.20 | Change payment minimum amount | PI | 1.26 |
Contact Information
Moving Media GmbH
Support Team
Bahnhofplatz 1-3 / PF#445
CH-9430 Sankt Margrethen SG
Switzerland
E-Mail: support@payment21.com
1. Payment21® API Integration and UI Tools
In order to begin accepting Bitcoin payments online, you must connect your website to our payment gateway. Clients must register with Payment21® in order to access the API integration details. Some parts of the application are not supported the by the API, however, further tools are available in the client account directly through the UI.
- E-Commerce Crypto API
- Payment21® JSON/REST API
- Payment21® Cashier Page
- Payment21® Payout Page
- E-Commerce UI Tools
- Payment21® E-Billing
- Payment21® Button
- OTC Exchange UI Tools
- Trading Page
- Buy Crypto
- Sell Crypto
1.1 Supported Use Cases
The underlying API supports the following use cases, which are in general sufficient to perform incoming and outgoing payment transactions in cryptocurrency.
1.2 Payment21® JSON/REST API:
A merchant can access the Payment21 Web Service by implementing our REST API in their web application.
Your software developer integrates the JSON API call directly in your application. If your consumer chooses “cryptocurrency" (on-chain or off-chain, XBT) as a payment method, the merchant’s system creates the REST request in accordance with the JSON integration documentation and sends it to the Payment21® web service. Payment21® responds by letting your system know whether the submitted information is valid. Your system then displays a confirmation page to the user to confirm the purchase and finalize the transaction. Finally, your system displays a transaction summary to the user containing all payment details as payment confirmation.
Benefits for the merchant:
-
Full session control
-
Use state-of-the-art API methods to communicate with Payment21®
-
Full transparency of transaction details
1.3 Payment21® Cashier Page:
We provide a checkout user interface containing payment details such as the Bitcoin address or payment request and a corresponding QR-Code.
Merchants simply redirect the purchaser to this cashier page, where the consumer initiates the on-chain or off-chain payment.
At the Payment21® Cashier Page, your consumer will see the required details for payment directly on our website. The consumer data will be transferred to the Payment21® system for verification, validation and processing. After the purchaser has completed the payment, he/she is redirected back to your site where you can display a confirmation page.
See an example on the demo store: https://app.payment21.com/demoshop.html.
1.4 Payment21® Payout Page
We provide a checkout user interface for payout requests allowing the payee to Login and receive a payout. Merchants simply redirect the payee to this payout page where the payee can Login and initiate the Bitcoin payout request.
Once the payee logins, the payee needs to go through the AML/KYC verification process before being eligible to accept the payout.
See an example on the demo payout: https://app.payment21.com/demopayout.html.
2. Payment21® JSON/REST API
The integration of Payment21® functionality is effected directly in the merchant’s system using REST.
If the merchant’s consumer chooses the crypto payment method, then the merchant’s system creates the REST-request by using the matching JSON definition and sends it to the Payment21® REST web service. The Payment21® REST web service responds by returning the corresponding JSON reply, to let your system know whether the request was valid, containing generated data for the payment, in case of a successful request. Your page then uses this reply to display a confirmation page to the consumer. The consumer has to confirm the purchase to finalize the transaction. You can display the transaction summary to the user with all payment details as a payment confirmation.
The Payment21® JSON/REST web service contains additional endpoints, to provide detailed information about each ongoing payment.
2.1 JSON/REST API Integration: How to integrate
A merchant can access the REST interface by coding the merchant’s website to communicate with our web service via the API.
The web service is accessible from https://app.payment21.com/api/mapi, supporting HTTPS only. All data is sent and received as JSON.
2.2 Service Operations
This document contains a number of important service operations.
Input Parameters to process transactions
Operation | Description |
---|---|
CreateVendor | Creates a sub-merchant account (needed to split consumers among different vendors of a merchant) |
UpdateVendor | Update previously created vendor data |
P21PayByCrypto | Creates a crypto payment request for the specified consumer |
PaymentStatus | Returns the status of the payment |
P21Payout | Creates a payout request from merchant to the specified payee |
PayoutStatus | Returns the status of the payout |
Input Parameters to differ or combine merchant ID and vendor ID
The system creates a new merchant when the 5-Step-Sign-Up is performed on the frontend, hence, there is no separate “CreateMerchant" operation supported through an API call. A merchant ID is assigned to your account automatically. You can find more details regarding this subject under “Integration Steps”.
To start sending transactions, you first need to create a vendor using the “CreateVendor” call.
Merchants can create multiple vendors (i.e. sub-merchant accounts) to allocate transactions to specific vendors, shops, agents, branches, business divisions etc.
If a merchant does not have multiple vendors, the merchant has to create a single vendor and treat these entry fields as wildcards. In this scenario, enter the company name of the merchant into the field “Company” etc. This wildcard vendor has to utilize the default merchant data and keep track of all transactions processed by the merchant.
The merchant account is the parent account, used for settling all the funds associated to the merchant and its vendors.
2.3 Calling Conventions
Payment21® follows best practice coding conventions.
Following common REST conventions, the API uses JSON (JavaScript Object Notation) to encode values and objects, which is widespread used and human-readable to allow easy debugging.
If the request can be fulfilled by Payment21®, the HTTP status code 200 will be returned, along with an optional response object, containing further details.
If the request is malformed, contains wrong or missing data, or we cannot process the request for any other reason, a HTTP status code different to 200 will be returned, e.g. 404 if the requested entity does not exist.
2.4 Supported HTTP Verbs
POST | Used for "CreateVendor" and P21PayByCrypto API calls |
PUT | Used for "UpdateVendor" (replace) API calls |
PATCH | Used for "UpdateVendor" (modify) API calls |
GET | Used for "PaymentStatus" API calls |
2.5 Authentication and Authorization
Payment21® maintains best practice security standards.
To authenticate yourself, you have to supply your Merchant-ID and API Key in every request. You will receive these credentials during the sign-up process and can change them through the Payment21® user interface.
Please be aware that your API key provides access to the Payment21® system in your name. Therefore, treat it with the same caution as a sensitive password; i.e. store it in a safe place and do not pass it to unauthorized personnel.
If your API key is lost or compromised, Payment21® can create a new one for you. For security reasons, we cannot recover your previous API key.
3. Payment21® Cashier Page
3.1 Introduction
The cashier page is made for a quick and simple integration and provides all the necessary user interactions of the purchaser to complete the payment.
You first announce the payment to Payment21® via the P21PayByCrypto API endpoint and redirect the purchaser to the cashier page hosted by Payment21.com. After the Bitcoin payment is made, the purchaser is redirected back to your site or to the confirmation page.
Once you have integrated our cashier page, your consumer can pay for goods and services by using “cryptocurrency” (on-chain or off-chain, XBT). The API will transfer the consumer data to the Payment21®-system for processing. Please note that the minimum payment amount for on-chain is 27.50 EUR and for off-chain 2.00 USD.
If a consumer profile already exists in your database (that is, the merchant’s database), you can prefill fields such as the consumer first name, last name, address and other contact information automatically. The consumer adds data related to the payment details into the fields, and makes the payment. We have additional security fields requesting details such as the consumer’s ID document, passport number and driver’s license number. The data entered will be stored in the Payment21® database for future resolution.
Payment21® will send an email to the consumer regarding his/her payment status. Additionally, the merchant receives a confirmation email containing the details of the transaction and purchase.
3.2 What the merchant’s consumers will see
Once your site is ready to use the API, you can add Payment21® crypto payments to your payment options.
Your consumer can now choose to pay with “cryptocurrency” (on-chain or off-chain, XBT).
Before the payment page is displayed for the consumer, the merchant sends information about the order through the API for verification, validation and authentication. This verification is done on the Payment21® side. Once the order information is successfully verified, the consumer will be redirected to the Payment21® crypto payment page. This is a secure form, which allows the consumer to pay using Bitcoin. See an example on the demo store:
https://app.payment21.com/demoshop.html.
As the first step, consumers have to explicitly agree with the Terms and Conditions by marking a checkbox and selecting the payment-type on-chain or off-chain.
Depending on the payment type selected, the consumer is shown a QR-code along with their payment details.
Consumers will see the crypto payment page with the QR-Code on the Payment21® cashier page. The consumer has to accept and submit the crypto payment using their Lightning or Bitcoin wallet depending on the payment type selected.
Depending on the payment type, once the consumer completes the crypto payment, on-chain transactions can be tracked over the blockchain, off-chain transactions get cleared instantaneously.
After the submitted transaction has been sent to the Payment21® system and has been detected by other Bitcoin nodes, the user is shown a confirmation page and a link that redirects them to the merchant’s site.
The consumer of the crypto transaction gets an email receipt, mentioning purchasing details and the status of the payment “Approved”, once the transaction is successful.
You as a merchant also get a notification email. This email message contains the consumer’s transaction information, such as amount and the transaction status of “Approved” on it.
3.3 Typical Inbound Payment Use Case
The integration of the Payment21® cashier page is easy, and consists only of a few steps.
The payment process is as follows:
-
The purchaser selects Payment21® for checkout
-
Your application calls the API method “P21PayByCrypto”
-
Your site redirects the purchaser to the returned URL
-
The purchaser will see the cashier page and pay by Crypto
-
After the payment is received, the purchaser is redirected back to your site
-
Call the API method PaymentStatus to check if the payment was successful
Step 1: The purchaser selects Payment21® for checkout
To enable purchasers to pay with Payment21, you have to add an option in your application.
Step 2: Your application calls the API method “P21PayByCrypto”
Your application calls the API method P21PayByCrypto to initialize the payment. This call includes details such as the amount, vendor and purchaser details.
Note: If you have not already created a vendor, you will need to create one using the API method CreateVendor.
The P21PayByCrypto response contains a unique transaction-ID, which should be stored. You can use it to retrieve the status of the payment.
The second value returned is a URL used subsequently.
Step 3: Your site redirects the purchaser to the returned URL
You should now redirect the purchaser to the URL of the Payment21® Cashier Page retrieved in the P21PayByCrypto Call.
Step 4: The purchaser will see the cashier page and pay by Bitcoin
As shown in the previous section, the purchaser can see the currency amount, fair value rate and the resulting Bitcoin amount. He can use a local Lightning or Bitcoin wallet and use a QR-Code to send the requested amount to Payment21®.
Step 5: After the payment is received, the purchaser is redirected back to your site
We are continuously monitoring the Bitcoin blockchain to detect the Bitcoin transaction sent by the purchaser instantly. After the requested amount is received, we will redirect the purchaser from our cashier page back to your site. The URL will also include the Transaction-ID returned in step two.
Step 6: Call the API method PaymentStatus to check if the payment was successful
You can call the API method PaymentStatus to check if the payment was successful and show a confirmation page to the purchaser.
Note: You can query the PaymentStatus at any time. We recommend checking the status after a short period of time in case the purchaser has interrupted the flow (e.g. by closing their browser window).
4. Payment21® Payout Page
4.1 Introduction
The payout page is made for a quick and simple integration and provides all the necessary user interactions of the payee to complete the payout.
4.2 Typical Outbound Payment Use Case
The integration of the Payment21® payout page consists of a few steps.
Step 1: The payee selects Payment21® for withdrawals (payout)
You have to add an option in your application for withdrawals (payout).
Step 2: Your application calls the API method “P21Payout”
Your application calls the API method P21Payout to initialize the payout. This call includes details such as the amount of the chosen cryptocurrency, vendor and payee details. The P21Payout response contains a unique transaction-ID, which should be stored. You can use it to retrieve the status of the payout. The second value which is returned is a redirectURL used subsequently.
Step 3: Your site redirects the payee to the returned redirectURL
You should now redirect the payee to the redirectURL which actually represents the Payment21® Payout Page.
Step 4: The payee views the Payment21® Payout Page, logs-in, completes AML/KYC-verification, and enters the Bitcoin address
The payee can see the requested payout amount and the corresponding bitcoin amount that will be sent to the payee. Before starting the payout, the payee needs to login, complete AML/KYC-verification, and enters a valid Bitcoin address.
Step 5: The payee confirms the payout
After the action items of Step 4 have been completed, the payee confirms the payout.
Step 6: Call the API method PayoutStatus to check the status of the payout
You can call the API method PayoutStatus at any time to check the status of the payout.
5. Payment21® E-Billing
5.1 Introduction
The E-Billing function is used to issue invoices to consumers.
There is no need to integrate an E-Billing API, since we are generating a unique URL for every invoice to be paid. To see a complete guide on how to use our E-Billing tool, follow this link:
https://payment21.com/support/faqs
6. Payment21® Button
6.1 Introduction
The Payment21® Button is not exposed through an API, but through the Payment21.com UI.
The Payment21® Button is used as an alternative for the integration of inbound payments. Instead of doing an API integration, it is possible to generate a payment button bound to an item (product), having a fixed price. The user needs to log in with his account and create buttons for each product separately. To see a guide on how to create a Payment21® Button, follow this link:
https://payment21.com/support/faqs
The generated button (HTML) can be copied to any site, providing a simple way of making an inbound payment with just one click.
7. Payment21® OTC Exchange
7.1 Trading Page
Payment21® operates an enterprise-level OTC Exchange, processing domestic and international buy & sell transactions through bank transfers.
There is no JSON/REST API for the Payment21® OTC Exchange. The only interaction with the OTC Exchange feature is through our Payment21.com UI. When the user logs in to the Payment21 application and navigates through the menus, he will find the OTC Exchange right away. The UI is built to be completely self-explanatory and therefore does not require a guide.
If questions regarding the OTC Exchange arise, please refer to this link:
https://payment21.com/support/faqs
7.2 Buy Crypto
Payment21 provides the possibility to buy cryptocurrencies with fiat. It is a simple and few-clicks solution.
There is no API to create buy trades. This is only done through the Payment21.com UI (when logged in). The UI is built to be completely self-explanatory and therefore does not require a guide.
7.3 Sell Crypto
Payment21 provides the possibility to sell cryptocurrencies for fiat. It is a simple and few-clicks solution.
There is no API to create sell trades. This is only done through the Payment21.com UI (when logged in). The UI is built to be completely self-explanatory and therefore does not require a guide.
8. Integration steps E-Commerce
8.1 Live environment
To start integration on the live environment, log in with your merchant account and navigate to the integration steps:
After clicking on “Generate Merchant API Key”, you will see your merchant ID and your API key as shown below:
Use your merchant ID and API key in the API integration.
8.2 Sandbox environment
Payment21 also provides a separate sandbox environment to test the Payment21® Bitcoin Cashier System, using the Bitcoin Testnet:
https://sandbox.corp.payment21.com Username: sandboxtestapi21@mailinator.com Password: Abcd123456*
Please use the following Sandbox Merchant information in your tests in the sandbox environment:
-
Merchant ID: 1024210
-
Vendor ID: 1024213
-
Merchant API Key: Generate one-time new API-Key from Sandbox
8.3 Bitcoin Testnet
If you want to test our Bitcoin Cashier System with the Bitcoin Testnet, you need to set up your Test Wallet first.
The Bitcoin Testnet is an alternative Bitcoin blockchain, to be used for testing. Testnet coins are separate and distinct from actual bitcoins, and are never supposed to have any value. This allows application developers and/or Bitcoin testers to experiment, without having to use real bitcoins.
https://en.bitcoin.it/wiki/Testnet
If you want to test the Payment21® Bitcoin Cashier System with real bitcoins, you need to set up your Bitcoin Wallet and purchase bitcoins first.
https://bitcoin.org/en/getting-started
9. Appendix
9.1 Supported processing currencies
Payment21® supports the following processing currencies for incoming and outgoing transactions.
Currency | Description |
---|---|
USD | United States Dollar |
EUR | Euro |
GBP | British Pound |
CHF | Swiss Franc |
JPY | Japanese Yen |
The amounts for all currencies are expressed as decimal numbers.
9.2 API Response & Error Codes
Payment21® provide a full set of response and error codes.
The JSON/REST API will return HTTP Status Code 200 if the request was processed successfully. Other codes signal errors as defined in the HTTP Protocol. To provide detailed information about the cause, an error object will be returned. It contains a field called “error” with a string that is described in the table below.
Error | HTTP Status | Message | Code |
---|---|---|---|
OK | 200 | Request was successful | - |
BAD_REQUEST | 400 | General error, e.g. the request contained invalid data | 7 |
LOW_PAYMENT_AMOUNT | 400 | Low payment amount. Please refer to documentation for minimum payment amount supported | 80 |
HTTP_REQUEST_METHOD_NOT_SUPPORTED | 400 | The requested HTTP verb is not supported | 113 |
WRONG_USERNAME_OR_PASSWORD | 401 | Wrong ‘username’, ‘password’ or ‘apiKey’ provided | 8 |
MERCHANT_DISABLED | 403 | The merchant account is disabled | 34 |
MERCHANT_NOT_APPROVED | 403 | The merchant is currently not approved. Please approve the merchant before proceeding | 50 |
PURCHASER_NOT_VERIFIED | 403 | The purchaser is not verified. Please verify it before proceeding | 38 |
PURCHASER_DISABLED | 403 | The Purchaser has been disabled. Please enable it before proceeding | 117 |
MAPI_UNKNOWN_VENDOR | 404 | Cannot find vendor with the given ID | 101 |
MAPI_REDIRECT_URL_MISSING | 400 | Merchant didn’t specify RedirectURL. Please specify RedirectURL before proceeding | 103 |
ENTITY_NOT_FOUND | 404 | The entity you are requesting is not found | 3 |
MAPI_CONTACT_CUSTOMER_SUPPORT | 403 | The call couldn’t be completed, contact Payment21® customer support for manual resolution | 102 |
INTERNAL_SERVER_ERROR | 500 | An unknown error occurred, please try again later or contact Payment21® for clarification | 2 |
INVALID_ARGUMENT_EMAIL | 400 | Invalid email. Please specify valid email address | 118 |
INVALID_ARGUMENT_DELIVERY_LEVEL | 400 | Please specify ‘deliveryLevel’ argument | 119 |
ANNUAL_MERCHANT_LIMIT | 400 | The merchant has reached the annual limit. Please contact Payment21® customer support or upgrade your merchant tier | 123 |
VELOCITY_MERCHANT_LIMIT | 400 | The merchant has reached the daily limit. Please contact Payment21® customer support or upgrade your merchant tier | 124 |
HTTP/1.1 404 Not Found
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
Date: Thu, 14 Jan 2016 22:08:07 GMT
Connection: close
Content-Length: 28
{
"error":"ENTITY_NOT_FOUND",
"code": 3,
"message": "The entity you are requesting is not found"
}
Payment21® Crypto (CreateVendor) Validation Error Response Example 1:
HTTP/1.1 400 Bad Request
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
{
"error": "BAD_REQUEST",
"code": 7,
"message": "General error, e.g. the request contained invalid data",
"fieldErrors": [
{
"field": "email",
"message": "may not be null"
},
{
"field": "company",
"message": "may not be null"
}
]
}
Payment21® Crypto (CreateVendor) Validation Error Response Example 2:
HTTP/1.1 400 Bad Request
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Content-Type: application/json;charset=UTF-8
{
"error": "BAD_REQUEST",
"code": 7,
"message": "General error, e.g. the request contained invalid data",
"fieldErrors": [
{
"field": "company",
"message": "size must be between 1 and 50"
},
{
"field": "products",
"message": "size must be between 0 and 50"
},
]
}
API Reference ¶
CreateVendor ¶
CreateVendorPOST/api/mapi/createVendor
This request provides all required information in order to assign a new vendor to a particular merchant. This will allow sending payments for a particular vendor and tracking transactions separately. As a response – you will receive a newly generated vendor-ID, which has to be stored and used in other interface requests.
Example URI
Headers
Content-Type: application/json;charset=UTF-8
apiKey: apiKeyDEMO
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Content-Length: 1671
Body
{
"merchantId": -1,
"email": "info@abccompany.com",
"company": "abc company",
"monthlyTnxNum": "500",
"avgTnxSize": "20",
"refunds": "5",
"chargebacks": "2",
"affiliate": "affiliateName",
"ownershipType": "SoleProprietor",
"dba": "Slingshot",
"billingAddress": "123 90th Street",
"billingPostalCode": "11209",
"billingCity": "Brooklyn",
"billingState": "N.Y.",
"billingCountry": "USA",
"mailingAddress": "123 90th Street",
"mailingPostalCode": "11209",
"mailingCity": "Brooklyn",
"mailingState": "N.Y.",
"mailingCountry": "USA",
"businessAddress": "123 90th Street",
"businessPostalCode": "11209",
"businessCity": "Brooklyn",
"businessState": "N.Y.",
"businessCountry": "USA",
"phone": "718 123 4567",
"fax": "718 123 4568",
"taxIdNumber": "123456578",
"branch": "Bay Ridge",
"mcc": 1234,
"products": "personal hygiene products",
"license": "5678890",
"licenseGeolocation": "USA",
"webUrl": "http://www.abccompany.com/admin",
"contractingParty": "contracting party name",
"signingPerson": "Boss X",
"technicalContact": "Technician Y",
"technicalEmail": "support@abccompany.com",
"technicalPhone": "718 098 7654",
"ecommerceUrl": "http://www.abccompany.com",
"ipAddress": "0.0.0.0",
"billingDescriptor": "billingDescriptor",
"beneficiaryName": "John Doe Beneficiary",
"beneficiaryDOB": "1981-01-11",
"beneficiaryEquityOwnership": "0.65",
"beneficiaryAddress": "765 59th Street",
"beneficiaryCity": "Brooklyn",
"beneficiaryState": "N.Y.",
"beneficiaryCountry": "USA",
"beneficiaryPhone": "718 346 3622",
"beneficiaryIdDoc": "9393373",
"beneficiaryIdDocCountry": "USA",
"beneficiaryCitizenship": "USA",
"beneficiaryDrivingLicence": "81224345",
"deliveryLevel": 6
}
Schema
{
"title": "CreateVendorRequest",
"description": "Input parameters for the operation CreateVendor",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com"
},
"apiKey": {
"type": "string",
"description": "Merchant API Key as assigned by Payment21.com",
"maxLength": 50,
"in": "header|body"
},
"email": {
"type": "string",
"description": "Vendor email",
"maxLength": 50,
"minLength": 1
},
"company": {
"type": "string",
"description": "Vendor company name",
"maxLength": 50,
"minLength": 1
},
"monthlyTnxNum": {
"type": "string",
"description": "Potential number of monthly transactions",
"maxLength": 50
},
"avgTnxSize": {
"type": "string",
"description": "Average transaction size",
"maxLength": 50
},
"refunds": {
"type": "string",
"description": "Refunds per month",
"maxLength": 50
},
"chargebacks": {
"type": "string",
"description": "Chargebacks per month",
"maxLength": 50
},
"affiliate": {
"type": "string",
"description": "Vendor affiliate name",
"maxLength": 50
},
"ownershipType": {
"type": "string",
"enum": [
"SoleProprietor",
"Corporate"
],
"description": "Ownership type: SoleProprietor, Corporate"
},
"dba": {
"type": "string",
"description": "Vendor trade name",
"maxLength": 50
},
"billingAddress": {
"type": "string",
"description": "Registration addres",
"maxLength": 50
},
"billingPostalCode": {
"type": "string",
"description": "Registration postal code",
"maxLength": 50
},
"billingCity": {
"type": "string",
"description": "Registration city",
"maxLength": 50
},
"billingState": {
"type": "string",
"description": "Registration state",
"maxLength": 50
},
"billingCountry": {
"type": "string",
"description": "Country of registration, ISO 3166",
"maxLength": 50
},
"mailingAddress": {
"type": "string",
"description": "Physical location address",
"maxLength": 50
},
"mailingPostalCode": {
"type": "string",
"description": "Physical location postal code",
"maxLength": 50
},
"mailingCity": {
"type": "string",
"description": "Physical location city",
"maxLength": 50
},
"mailingState": {
"type": "string",
"description": "Physical location state",
"maxLength": 50
},
"mailingCountry": {
"type": "string",
"description": "Country of physical location, ISO 3166",
"maxLength": 50
},
"businessAddress": {
"type": "string",
"description": "Business location address",
"maxLength": 50
},
"businessPostalCode": {
"type": "string",
"description": "Business location postal code",
"maxLength": 50
},
"businessCity": {
"type": "string",
"description": "Business location city",
"maxLength": 50
},
"businessState": {
"type": "string",
"description": "Business location state",
"maxLength": 50
},
"businessCountry": {
"type": "string",
"description": "Country of business location, ISO 3166",
"maxLength": 50
},
"phone": {
"type": "string",
"description": "Vendor phon",
"maxLength": 50
},
"fax": {
"type": "string",
"description": "Vendor fax",
"maxLength": 50
},
"taxIdNumber": {
"type": "string",
"description": "Vendor tax number",
"maxLength": 50
},
"branch": {
"type": "string",
"description": "Vendor branch of operation",
"maxLength": 50
},
"mcc": {
"type": "integer",
"description": "Vendor category code (ISO 18245)"
},
"products": {
"type": "string",
"description": "Vendor products description",
"maxLength": 50
},
"license": {
"type": "string",
"description": "License ID of the vendor required in case MCC is within specific values",
"maxLength": 50
},
"licenseGeolocation": {
"type": "string",
"description": "Country of license applicability, ISO 3166",
"maxLength": 50
},
"webUrl": {
"type": "string",
"description": "Vendor website UR",
"maxLength": 50
},
"contractingParty": {
"type": "string",
"description": "Vendor contracting party name",
"maxLength": 50
},
"signingPerson": {
"type": "string",
"description": "Signing person",
"maxLength": 50
},
"technicalContact": {
"type": "string",
"description": "Technical contact",
"maxLength": 50
},
"technicalEmail": {
"type": "string",
"description": "Email of technical contact",
"maxLength": 50
},
"technicalPhone": {
"type": "string",
"description": "Phone number of technical contact",
"maxLength": 50
},
"ecommerceUrl": {
"type": "string",
"description": "URL of the shop where consumers are purchasing goods and services",
"maxLength": 50
},
"ipAddress": {
"type": "string",
"description": "Vendor IP address",
"maxLength": 50
},
"billingDescriptor": {
"type": "string",
"description": "Billing descriptor to be used in the transactions description as vendor billing descriptor",
"maxLength": 50
},
"beneficiaryName": {
"type": "string",
"description": "Name of primary beneficial owner of contracting party",
"maxLength": 50
},
"beneficiaryDOB": {
"type": "string",
"description": "Vendor beneficiary date of birth",
"format": "date"
},
"beneficiaryEquityOwnership": {
"type": "string",
"description": "Vendor beneficiary equity ownership, in percent",
"maxLength": 50
},
"beneficiaryAddress": {
"type": "string",
"description": "Vendor beneficiary address",
"maxLength": 50
},
"beneficiaryCity": {
"type": "string",
"description": "Vendor beneficiary city",
"maxLength": 50
},
"beneficiaryState": {
"type": "string",
"description": "Vendor beneficiary state",
"maxLength": 50
},
"beneficiaryCountry": {
"type": "string",
"description": "Vendor beneficiary country, ISO 3166",
"maxLength": 50
},
"beneficiaryPhone": {
"type": "string",
"description": "Vendor beneficiary phone number",
"maxLength": 50
},
"beneficiaryIdDoc": {
"type": "string",
"description": "Vendor beneficiary ID document",
"maxLength": 50
},
"beneficiaryIdDocCountry": {
"type": "string",
"description": "Vendor beneficiary ID document issue country, ISO 3166",
"maxLength": 50
},
"beneficiaryCitizenship": {
"type": "string",
"description": "Vendor beneficiary citizenship, ISO 3166",
"maxLength": 50
},
"beneficiaryDrivingLicence": {
"type": "string",
"description": "Vendor beneficiary driving license",
"maxLength": 50
},
"deliveryLevel": {
"type": "integer",
"description": "The number of confirmations in the Bitcoin blockchain to wait for until the status Ready for Delivery is reached for a given vendor's transaction"
}
},
"required": [
"merchantId",
"email",
"company"
]
}
200
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 22:17:35 GMT
Connection: close
Content-Length: 130
Body
{
"vendorId": "59"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"vendorId": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Vendor ID assigned by Payment21.com"
}
},
"required": [
"vendorId"
]
}
P21PayByCrypto ¶
P21PayByCryptoPOST/api/mapi/p21PayByCrypto
Example URI
Input Parameters (An object of “Payment21® Crypto Payment (P21PayByCrypto)” with the following member variables):
Headers
Content-Type: application/json;charset=UTF-8
apiKey: apiKeyDEMO
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Content-Length: 539
Body
{
"merchantId": -1,
"vendorId": 59,
"orderAmount": 20,
"orderCurrency": "USD",
"itemDescription": "Milk",
"itemCode": "a17",
"partnerTransId": "pt8274",
"merchantConsumerId": "-2",
"merchantTransId": "mt32789",
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1970-12-27",
"docId": "D234890",
"phone": "+1123456789",
"email": "john@abccompanyChange.com",
"address1": "123 First Street",
"address2": "",
"driverLicenseNumber": "ddr-1234",
"passportNumber": "GW34576",
"city": "New York",
"state": "NY",
"postalCode": "12345",
"country": "US",
"deliveryLevel": 3,
"notificationUrl": "http://www.abccompany.com/IPN",
"redirectBackToUrl": "http://www.abccompany.com/checkout"
}
Schema
{
"title": "P21PayByCryptoRequest",
"description": "Input parameters for the operation P21PayByCrypto",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com"
},
"vendorId": {
"type": "integer",
"description": "Vendor ID as assigned by Payment21.com"
},
"apiKey": {
"type": "string",
"description": "Merchant API Key as assigned by Payment21.com",
"maxLength": 50,
"in": "header|body"
},
"orderAmount": {
"type": "number",
"description": "Order amount. Must be greater than 8"
},
"orderCurrency": {
"type": "string",
"description": "Currency code, ISO 4217"
},
"itemDescription": {
"type": "string",
"description": "Item description",
"maxLength": 50,
"minLength": 1
},
"itemCode": {
"type": "string",
"description": "Code of the item",
"maxLength": 50,
"minLength": 1
},
"partnerTransId": {
"type": "string",
"description": "Merchant partner transaction I",
"maxLength": 36
},
"merchantConsumerId": {
"type": "string",
"description": "An ID which uniquely identifies the purchaser of the given vendor. Successive calls have to use the same id for the same purchaser.",
"maxLength": 36,
"minLength": 1
},
"merchantTransId": {
"type": "string",
"description": "Merchant transaction ID",
"maxLength": 36
},
"firstName": {
"type": "string",
"description": "Consumer's first name",
"maxLength": 50,
"minLength": 1
},
"lastName": {
"type": "string",
"description": "Consumer's last name",
"maxLength": 50,
"minLength": 1
},
"dateOfBirth": {
"type": "string",
"description": "Consumer's date of birth",
"format": "date"
},
"docId": {
"type": "string",
"description": "Identification document number",
"maxLength": 50,
"minLength": 1
},
"phone": {
"type": "string",
"description": "Consumer's phone",
"maxLength": 50
},
"email": {
"type": "string",
"description": "Consumer's email address",
"maxLength": 50,
"minLength": 1
},
"address1": {
"type": "string",
"description": "Consumer's address field one",
"maxLength": 50,
"minLength": 1
},
"address2": {
"type": "string",
"description": "Consumer's address field two",
"maxLength": 50
},
"driverLicenseNumber": {
"type": "string",
"description": "Consumer's driver license number",
"maxLength": 50
},
"passportNumber": {
"type": "string",
"description": "Consumer's passport number",
"maxLength": 50
},
"city": {
"type": "string",
"description": "Consumer's address city",
"maxLength": 50,
"minLength": 1
},
"state": {
"type": "string",
"description": "Consumer's address state code",
"maxLength": 50
},
"postalCode": {
"type": "string",
"description": "5 digit postal code in the consumer's country (or ZIP)",
"maxLength": 10,
"minLength": 1
},
"country": {
"type": "string",
"description": "Consumer's country, e.g. 'United Kingdom'",
"maxLength": 50
},
"deliveryLevel": {
"type": "integer",
"description": "The number of confirmations in the Bitcoin blockchain to wait for until the status Ready for Delivery is reached. If set, it needs to be greater than 0, since we do not support 0 delivery level. See operation PaymentStatus for more details."
},
"notificationUrl": {
"type": "string",
"description": "IPN endpoint for payment status changes"
},
"redirectBackToUrl": {
"type": "string",
"description": "Redirect URL"
}
},
"required": [
"merchantId",
"vendorId",
"orderAmount",
"orderCurrency",
"itemDescription",
"itemCode",
"merchantConsumerId",
"firstName",
"lastName",
"email",
"country"
]
}
200
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"transactionId": "587a1892-18be-4836-aa0c-a7f7255cf974",
"redirectTo": "payment.html#/!/?transactionId=f687a78c-8496-4cbd-a4f9-b3ec107a2abb"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"transactionId": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Contains transaction ID of the added transaction"
},
"redirectTo": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Relative URL the purchaser needs to be redirected to"
}
},
"required": [
"transactionId",
"redirectTo"
]
}
401
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"error": "WRONG_USERNAME_OR_PASSWORD",
"code": 50,
"message": "Wrong 'username', 'password' or 'apiKey' provided"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Error as found in the Error Code List"
},
"code": {
"type": "integer",
"description": "Error code as numerical value"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Descriptive message for the error"
}
},
"required": [
"error",
"code",
"message"
]
}
PaymentStatus ¶
PaymentStatusGET/api/mapi/paymentStatus/{merchantId}/{transactionId}
Example URI
- merchantId
number
(required) Example: -1- transactionId
string
(required) Example: 4e1736f3-17bd-4477-9159-3bcfa8685bbd
Headers
apiKey: demoShopApiKey
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Schema
{
"description": "Path and header parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"parameters": {
"apiKey": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Merchant API Key as assigned by Payment21.com",
"in": "header"
},
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com",
"in": "path"
},
"transactionId": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The transaction ID for which to get the status",
"in": "path"
}
},
"required": [
"apiKey",
"merchantId",
"transactionId"
]
}
200
Return Response:
Field | Description |
---|---|
Status | The status of the requested transaction. Possible values: Initialized: The Payment was initialized Awaiting_Payment: The purchaser has accepted the terms & conditions and is preparing to pay Authorized: The payment has been triggered by the purchaser and was seen in the bitcoin network. The purchaser is redirected from the cashier page back to your webshop. Ready_for_Delivery: The number of confirmations specified in the p21PayByCrypto call have been reached Cleared: The Payment was successful and will be settled Settled: The Payment was settled Expired: The Payment has expired Canceled: The Payment has been canceled by the purchaser Failed: The Payment has failed for other reasons |
Confirmations |
1..n: The number of confirmations in the Bitcoin network for the Bitcoin transaction from the purchaser 0: if the transaction is broadcast but not included in the blockchain -1: If no transaction is received or an error occurred |
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"status": "Awaiting_Payment",
"confirmations": -1,
"payment": {
"bitcoinAddress": "n1qapPUNvYdYqVgokZDjBKsXHCoshhT5VF",
"bitcoinUrl": "bitcoin:n1qapPUNvYdYqVgokZDjBKsXHCoshhT5VF?amount=0.210604&r=https://localhost:3000/api/public/createBitcoinPaymentRequest/n1qapPUNvYdYqVgokZDjBKsXHCoshhT5VF",
"bitcoinDue": 0.210604,
"bitcoinPaid": 0
},
"quote": {
"purchaserName": "John Smith",
"merchantName": "abc vendor",
"amount": 50,
"amountBTC": 0.210604,
"quote": 237.412395,
"quoteId": "9270",
"timeoutSec": 600,
"remainingSec": 589,
"itemDescription": "Milk",
"itemCode": "a17",
"purchaserCountry": "US",
"vendorEmail": "info@test.com",
"vendorAddress": "BO Box 480127",
"vendorPostalCode": "Charlotte",
"vendorCity": "287895",
"vendorState": "NC",
"vendorCountry": "US",
"redirectBackToUrl": "demoshop.html#/!/?transactionId=980f4fe5-4702-4259-8d93-9ee60c9ee4a9",
"currency": "CHF"
}
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The status of the requested transaction."
},
"confirmations": {
"type": "integer",
"description": "The number of confirmations in the Bitcoin network for the Bitcoin transaction from the purchaser"
},
"payment": {
"type": "object",
"properties": {
"bitcoinAddress": {
"type": "string",
"description": "Bitcoin address for sending the bitcoins"
},
"bitcoinDue": {
"type": "number",
"description": "Bitcoins still to be sent"
},
"bitcoinPaid": {
"type": "number",
"description": "Bitcoins already sent"
},
"bitcoinUrl": {
"type": "string",
"description": "Bitcoin URL accourding to the Bitcoin BIP:21 URI schema for making Bitcoin payments"
}
}
},
"quote": {
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Payment amount (in fiat currency)"
},
"currency": {
"type": "string",
"description": "The fiat currency for the payment amount"
},
"amountBTC": {
"type": "number",
"description": "Corresponding amount to be paid (in bitcoins)"
},
"itemDescription": {
"type": "string",
"description": "Item description",
"maxLength": 50,
"minLength": 1
},
"itemCode": {
"type": "string",
"description": "Code of the item",
"maxLength": 50,
"minLength": 1
},
"merchantName": {
"type": "string",
"description": "Name of the merchant",
"maxLength": 50,
"minLength": 1
},
"purchaserName": {
"type": "string",
"description": "Name of the purchaser",
"maxLength": 50,
"minLength": 1
},
"purchaserCountry": {
"type": "string",
"description": "Country of the purchaser"
},
"vendorEmail": {
"type": "string",
"description": "Email of the merchant/vendor"
},
"vendorAddress": {
"type": "string",
"description": "Address of the merchant/vendor"
},
"vendorCity": {
"type": "string",
"description": "City of the merchant/vendor"
},
"vendorPostalCode": {
"type": "string",
"description": "Postal code of the merchant/vendor"
},
"vendorState": {
"type": "string",
"description": "State of the merchant/vendor"
},
"vendorCountry": {
"type": "string",
"description": "Country of the merchant/vendor"
},
"quote": {
"type": "number",
"description": "Fiat to bitcoin exchange rate"
},
"quoteId": {
"type": "string",
"description": "Id of the quote"
},
"redirectBackToUrl": {
"type": "string",
"description": "Redirect URL after payment page"
},
"remainingSec": {
"type": "integer",
"description": "Remaining time (in seconds) until the quote expires"
},
"timeoutSec": {
"type": "integer",
"description": "Quote expiration time (in seconds)"
}
}
}
},
"required": [
"status"
]
}
401
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"error": "WRONG_USERNAME_OR_PASSWORD",
"code": 50,
"message": "Wrong 'username', 'password' or 'apiKey' provided"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Error as found in the Error Code List"
},
"code": {
"type": "integer",
"description": "Error code as numerical value"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Descriptive message for the error"
}
},
"required": [
"error",
"code",
"message"
]
}
P21Payout ¶
P21PayoutPOST/api/mapi/p21Payout
Example URI
Input Parameters (An object of “Payment21® Crypto Payout (P21Payout)” with the following member variables):
Headers
Content-Type: application/json;charset=UTF-8
apiKey: apiKeyDEMO
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Content-Length: 539
Body
{
"merchantId": -1,
"vendorId": 59,
"payoutAmount": 20,
"payoutCurrency": "USD",
"merchantConsumerId": "-2",
"merchantTransId": "mt32789",
"firstName": "John",
"lastName": "Smith",
"dateOfBirth": "1970-12-27",
"docId": "D234890",
"phone": "+1123456789",
"email": "john@abccompanyChange.com",
"address1": "123 First Street",
"address2": "",
"driverLicenseNumber": "ddr-1234",
"passportNumber": "GW34576",
"city": "New York",
"state": "NY",
"postalCode": "12345",
"country": "US"
}
Schema
{
"title" : "P21PayoutRequest",
"description" : "Input parameters for the operation P21Payout",
"type" : "object",
"$schema" : "http://json-schema.org/draft-04/schema#",
"properties" : {
"merchantId" : {
"type" : "integer",
"description" : "Merchant User ID as assigned by Payment21.com"
},
"vendorId" : {
"type" : "integer",
"description" : "Vendor ID as assigned by Payment21.com"
},
"apiKey" : {
"type" : "string",
"description" : "Merchant API Key as assigned by Payment21.com",
"maxLength" : 50,
"in": "header|body"
},
"payoutAmount" : {
"type" : "number",
"description" : “Payout amount."
},
"payoutCurrency" : {
"type" : "string",
"description" : "Currency code, ISO 4217"
},
"merchantConsumerId" : {
"type" : "string",
"description" : "An ID which uniquely identifies the purchaser of the given vendor. Successive calls have to use the same id for the same purchaser.",
"maxLength" : 36,
"minLength" : 1
},
"merchantTransId" : {
"type" : "string",
"description" : "Merchant payout ID",
"maxLength" : 36
},
"firstName" : {
"type" : "string",
"description" : "Consumer's first name",
"maxLength" : 50,
"minLength" : 1
},
"lastName" : {
"type" : "string",
"description" : "Consumer's last name",
"maxLength" : 50,
"minLength" : 1
},
"dateOfBirth" : {
"type" : "string",
"description" : "Consumer's date of birth",
"format" : "date"
},
"docId" : {
"type" : "string",
"description" : "Identification document number",
"maxLength" : 50,
"minLength" : 1
},
"phone" : {
"type" : "string",
"description" : "Consumer's phone",
"maxLength" : 50
},
"email" : {
"type" : "string",
"description" : "Consumer's email address",
"maxLength" : 50,
"minLength" : 1
},
"address1" : {
"type" : "string",
"description" : "Consumer's address field one",
"maxLength" : 50,
"minLength" : 1
},
"address2" : {
"type" : "string",
"description" : "Consumer's address field two",
"maxLength" : 50
},
"driverLicenseNumber" : {
"type" : "string",
"description" : "Consumer's driver license number",
"maxLength" : 50
},
"passportNumber" : {
"type" : "string",
"description" : "Consumer's passport number",
"maxLength" : 50
},
"city" : {
"type" : "string",
"description" : "Consumer's address city",
"maxLength" : 50,
"minLength" : 1
},
"state" : {
"type" : "string",
"description" : "Consumer's address state code",
"maxLength" : 50
},
"postalCode" : {
"type" : "string",
"description" : "5 digit postal code in the consumer's country (or ZIP)",
"maxLength" : 10,
"minLength" : 1
},
"country" : {
"type" : "string",
"description" : "Consumer's country, e.g. 'United Kingdom'",
"maxLength" : 50
},
"notificationUrl" : {
"type" : "string",
"description" : "IPN endpoint for payout status changes"
},
"redirectBackToUrl" : {
"type" : "string",
"description" : "Redirect URL"
}
},
"required": [
"merchantId",
"vendorId",
"payoutAmount",
"payoutCurrency",
"merchantConsumerId",
"firstName",
"lastName",
"email",
"country"
]
}
200
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"transactionId": "633d4fb2-dd0c-4d5b-87e7-c6b2349adbab",
"redirectTo": "payout.html#/!/?transactionId=633d4fb2-dd0c-4d5b-87e7-c6b2349adbab"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"transactionId": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Contains transaction ID of the added payout request”
},
"redirectTo": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Relative URL the payee needs to be redirected to"
}
},
"required": [
"transactionId",
"redirectTo"
]
}
401
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"error": "WRONG_USERNAME_OR_PASSWORD",
"code": 50,
"message": "Wrong 'username', 'password' or 'apiKey' provided"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Error as found in the Error Code List"
},
"code": {
"type": "integer",
"description": "Error code as numerical value"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Descriptive message for the error"
}
},
"required": [
"error",
"code",
"message"
]
}
Payout Status ¶
Payout StatusGET/api/mapi/payoutStatus/{merchantId}/{transactionId}
Example URI
- merchantId
number
(required) Example: -1- transactionId
string
(required) Example: 633d4fb2-dd0c-4d5b-87e7-c6b2349adbab
Headers
apiKey: demoShopApiKey
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Schema
{
"description": "Path and header parameters",
"$schema": "http://json-schema.org/draft-04/schema#",
"parameters": {
"apiKey": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Merchant API Key as assigned by Payment21.com",
"in": "header"
},
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com",
"in": "path"
},
"transactionId": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The transaction ID for which to get the status",
"in": "path"
}
},
"required": [
"apiKey",
"merchantId",
"transactionId"
]
}
200
Return Response:
Field | Description |
---|---|
Payout Status | The status of the requested payout. Possible values: Initialized: The Payout has been initialized Verified: The Payee confirms the payout Awaiting_Funding: Fiat funds get converted to cryptocurrency Funded: Funds have been exchanged in cryptocurrency Dangling: "Dangling" equals to "Pending" for manual processing by Payment21 Awaiting_Confirmation: The transaction was sent to the payee. Waiting for specified number of confirmations Finished: The Payout is successful Expired: The Payout has expired Canceled: The Payout has been canceled by the payee Failed: The Payout has failed for other reasons |
Code |
1..7: Positive code from 1-7 means the Payout is still in progress and the final status is not reached yet -2: When the payout status is Failed -3: When the payout status is Expired -4: When the payout status is Canceled |
Headers
Content-Type: application/json;charset=UTF-8
Body
{
"status":"Initialized",
"code": 1,
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"status": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "The status of the requested payout.”
},
“code”: {
"type": "integer",
"description": “Numeric code for the status“
}
},
"required": [
"status"
]
}
401
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 17:42:31 GMT
Connection: close
Content-Length: 135
Body
{
"error": "WRONG_USERNAME_OR_PASSWORD",
"code": 50,
"message": "Wrong 'username', 'password' or 'apiKey' provided"
}
Schema
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
"properties": {
"error": {
"type": "string",
"minLength": 1,
"maxLength": 50,
"description": "Error as found in the Error Code List"
},
"code": {
"type": "integer",
"description": "Error code as numerical value"
},
"message": {
"type": "string",
"minLength": 1,
"maxLength": 250,
"description": "Descriptive message for the error"
}
},
"required": [
"error",
"code",
"message"
]
}
UpdateVendor ¶
UpdateReplaceVendorPUT/api/mapi/updateVendor
This request updates all required information of a vendor associated to the given merchant. To identify the vendor, the ID returned from the CreateVendor API call has to be supplied.
Example URI
Headers
Content-Type: application/json;charset=UTF-8
apiKey: apiKeyDEMO
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Content-Length: 1671
Body
{
"id": 59,
"merchantId": -1,
"email": "info@abccompany.com",
"company": "abc company",
"monthlyTnxNum": "500",
"avgTnxSize": "20",
"refunds": "5",
"chargebacks": "2",
"affiliate": "affiliateName",
"ownershipType": "SoleProprietor",
"dba": "Slingshot",
"billingAddress": "123 90th Street",
"billingPostalCode": "11209",
"billingCity": "Brooklyn",
"billingState": "N.Y.",
"billingCountry": "USA",
"mailingAddress": "123 90th Street",
"mailingPostalCode": "11209",
"mailingCity": "Brooklyn",
"mailingState": "N.Y.",
"mailingCountry": "USA",
"businessAddress": "123 90th Street",
"businessPostalCode": "11209",
"businessCity": "Brooklyn",
"businessState": "N.Y.",
"businessCountry": "USA",
"phone": "718 123 4567",
"fax": "718 123 4568",
"taxIdNumber": "123456578",
"branch": "Bay Ridge",
"mcc": 1234,
"products": "personal hygiene products",
"license": "5678890",
"licenseGeolocation": "USA",
"webUrl": "http://www.abccompany.com/admin",
"contractingParty": "contracting party name",
"signingPerson": "Boss X",
"technicalContact": "Technician Y",
"technicalEmail": "support@abccompany.com",
"technicalPhone": "718 098 7654",
"ecommerceUrl": "http://www.abccompany.com",
"ipAddress": "0.0.0.0",
"billingDescriptor": "billingDescriptor",
"beneficiaryName": "John Doe Beneficiary",
"beneficiaryDOB": "1981-01-11",
"beneficiaryEquityOwnership": "0.65",
"beneficiaryAddress": "765 59th Street",
"beneficiaryCity": "Brooklyn",
"beneficiaryState": "N.Y.",
"beneficiaryCountry": "USA",
"beneficiaryPhone": "718 346 3622",
"beneficiaryIdDoc": "9393373",
"beneficiaryIdDocCountry": "USA",
"beneficiaryCitizenship": "USA",
"beneficiaryDrivingLicence": "81224345",
"deliveryLevel": 6
}
Schema
{
"title": "UpdateReplaceVendorRequest",
"description": "Input parameters for the operation UpdateReplaceVendor. Not specified optional properties will be set to null.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"id": {
"type": "integer",
"description": "The ID of the vendor to update as returned by CreateVendor"
},
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com"
},
"apiKey": {
"type": "string",
"description": "Merchant API Key as assigned by Payment21.com",
"maxLength": 50,
"in": "header|body"
},
"email": {
"type": "string",
"description": "Vendor email",
"maxLength": 50,
"minLength": 1
},
"company": {
"type": "string",
"description": "Vendor company name",
"maxLength": 50,
"minLength": 1
},
"monthlyTnxNum": {
"type": "string",
"description": "Potential number of monthly transactions",
"maxLength": 50
},
"avgTnxSize": {
"type": "string",
"description": "Average transaction size",
"maxLength": 50
},
"refunds": {
"type": "string",
"description": "Refunds per month",
"maxLength": 50
},
"chargebacks": {
"type": "string",
"description": "Chargebacks per month",
"maxLength": 50
},
"affiliate": {
"type": "string",
"description": "Vendor affiliate name",
"maxLength": 50
},
"ownershipType": {
"type": "string",
"enum": [
"SoleProprietor",
"Corporate"
],
"description": "Ownership type: SoleProprietor, Corporate"
},
"dba": {
"type": "string",
"description": "Vendor trade name",
"maxLength": 50
},
"billingAddress": {
"type": "string",
"description": "Registration addres",
"maxLength": 50
},
"billingPostalCode": {
"type": "string",
"description": "Registration postal code",
"maxLength": 50
},
"billingCity": {
"type": "string",
"description": "Registration city",
"maxLength": 50
},
"billingState": {
"type": "string",
"description": "Registration state",
"maxLength": 50
},
"billingCountry": {
"type": "string",
"description": "Country of registration, ISO 3166",
"maxLength": 50
},
"mailingAddress": {
"type": "string",
"description": "Physical location address",
"maxLength": 50
},
"mailingPostalCode": {
"type": "string",
"description": "Physical location postal code",
"maxLength": 50
},
"mailingCity": {
"type": "string",
"description": "Physical location city",
"maxLength": 50
},
"mailingState": {
"type": "string",
"description": "Physical location state",
"maxLength": 50
},
"mailingCountry": {
"type": "string",
"description": "Country of physical location, ISO 3166",
"maxLength": 50
},
"businessAddress": {
"type": "string",
"description": "Business location address",
"maxLength": 50
},
"businessPostalCode": {
"type": "string",
"description": "Business location postal code",
"maxLength": 50
},
"businessCity": {
"type": "string",
"description": "Business location city",
"maxLength": 50
},
"businessState": {
"type": "string",
"description": "Business location state",
"maxLength": 50
},
"businessCountry": {
"type": "string",
"description": "Country of business location, ISO 3166",
"maxLength": 50
},
"phone": {
"type": "string",
"description": "Vendor phon",
"maxLength": 50
},
"fax": {
"type": "string",
"description": "Vendor fax",
"maxLength": 50
},
"taxIdNumber": {
"type": "string",
"description": "Vendor tax number",
"maxLength": 50
},
"branch": {
"type": "string",
"description": "Vendor branch of operation",
"maxLength": 50
},
"mcc": {
"type": "integer",
"description": "Vendor category code (ISO 18245)"
},
"products": {
"type": "string",
"description": "Vendor products description",
"maxLength": 50
},
"license": {
"type": "string",
"description": "License ID of the vendor required in case MCC is within specific values",
"maxLength": 50
},
"licenseGeolocation": {
"type": "string",
"description": "Country of license applicability, ISO 3166",
"maxLength": 50
},
"webUrl": {
"type": "string",
"description": "Vendor website UR",
"maxLength": 50
},
"contractingParty": {
"type": "string",
"description": "Vendor contracting party name",
"maxLength": 50
},
"signingPerson": {
"type": "string",
"description": "Signing person",
"maxLength": 50
},
"technicalContact": {
"type": "string",
"description": "Technical contact",
"maxLength": 50
},
"technicalEmail": {
"type": "string",
"description": "Email of technical contact",
"maxLength": 50
},
"technicalPhone": {
"type": "string",
"description": "Phone number of technical contact",
"maxLength": 50
},
"ecommerceUrl": {
"type": "string",
"description": "URL of the shop where consumers are purchasing goods and services",
"maxLength": 50
},
"ipAddress": {
"type": "string",
"description": "Vendor IP address",
"maxLength": 50
},
"billingDescriptor": {
"type": "string",
"description": "Billing descriptor to be used in the transactions description as vendor billing descriptor",
"maxLength": 50
},
"beneficiaryName": {
"type": "string",
"description": "Name of primary beneficial owner of contracting party",
"maxLength": 50
},
"beneficiaryDOB": {
"type": "string",
"description": "Vendor beneficiary date of birth",
"format": "date"
},
"beneficiaryEquityOwnership": {
"type": "string",
"description": "Vendor beneficiary equity ownership, in percent",
"maxLength": 50
},
"beneficiaryAddress": {
"type": "string",
"description": "Vendor beneficiary address",
"maxLength": 50
},
"beneficiaryCity": {
"type": "string",
"description": "Vendor beneficiary city",
"maxLength": 50
},
"beneficiaryState": {
"type": "string",
"description": "Vendor beneficiary state",
"maxLength": 50
},
"beneficiaryCountry": {
"type": "string",
"description": "Vendor beneficiary country, ISO 3166",
"maxLength": 50
},
"beneficiaryPhone": {
"type": "string",
"description": "Vendor beneficiary phone number",
"maxLength": 50
},
"beneficiaryIdDoc": {
"type": "string",
"description": "Vendor beneficiary ID document",
"maxLength": 50
},
"beneficiaryIdDocCountry": {
"type": "string",
"description": "Vendor beneficiary ID document issue country, ISO 3166",
"maxLength": 50
},
"beneficiaryCitizenship": {
"type": "string",
"description": "Vendor beneficiary citizenship, ISO 3166",
"maxLength": 50
},
"beneficiaryDrivingLicence": {
"type": "string",
"description": "Vendor beneficiary driving license",
"maxLength": 50
},
"deliveryLevel": {
"type": "integer",
"description": "The number of confirmations in the Bitcoin blockchain to wait for until the status Ready for Delivery is reached for a given vendor's transaction"
}
},
"required": [
"id",
"merchantId",
"email",
"company"
]
}
200
This method does not return any information if successfully called. Please see the API error section for further details.
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 22:17:35 GMT
Connection: close
Content-Length: 0
UpdateModifyVendorPATCH/api/mapi/updateVendor
This request updates all required information of a vendor associated to the given merchant. To identify the vendor, the ID returned from the CreateVendor API call has to be supplied.
Example URI
Headers
Content-Type: application/json;charset=UTF-8
apiKey: apiKeyDEMO
Accept: application/json, application/*+json
Cache-Control: no-cache
Pragma: no-cache
User-Agent: Java/1.8.0_25
Host: app.payment21.com
Connection: close
Content-Length: 1671
Body
{
"id": 59,
"merchantId": -1,
"email": "info@abccompany.com",
"company": "abc company",
"ecommerceUrl": "http://www.abccompany.com",
"ipAddress": "0.0.0.0"
}
Schema
{
"title": "UpdateModifyVendorRequest",
"description": "Input parameters for the operation UpdateModifyVendor. Only specified properties will be updated.",
"type": "object",
"$schema": "http://json-schema.org/draft-04/schema#",
"properties": {
"id": {
"type": "integer",
"description": "The ID of the vendor to update as returned by CreateVendor"
},
"merchantId": {
"type": "integer",
"description": "Merchant User ID as assigned by Payment21.com"
},
"apiKey": {
"type": "string",
"description": "Merchant API Key as assigned by Payment21.com",
"maxLength": 50,
"in": "header|body"
},
"email": {
"type": "string",
"description": "Vendor email",
"maxLength": 50,
"minLength": 1
},
"company": {
"type": "string",
"description": "Vendor company name",
"maxLength": 50,
"minLength": 1
},
"monthlyTnxNum": {
"type": "string",
"description": "Potential number of monthly transactions",
"maxLength": 50
},
"avgTnxSize": {
"type": "string",
"description": "Average transaction size",
"maxLength": 50
},
"refunds": {
"type": "string",
"description": "Refunds per month",
"maxLength": 50
},
"chargebacks": {
"type": "string",
"description": "Chargebacks per month",
"maxLength": 50
},
"affiliate": {
"type": "string",
"description": "Vendor affiliate name",
"maxLength": 50
},
"ownershipType": {
"type": "string",
"enum": [
"SoleProprietor",
"Corporate"
],
"description": "Ownership type: SoleProprietor, Corporate"
},
"dba": {
"type": "string",
"description": "Vendor trade name",
"maxLength": 50
},
"billingAddress": {
"type": "string",
"description": "Registration addres",
"maxLength": 50
},
"billingPostalCode": {
"type": "string",
"description": "Registration postal code",
"maxLength": 50
},
"billingCity": {
"type": "string",
"description": "Registration city",
"maxLength": 50
},
"billingState": {
"type": "string",
"description": "Registration state",
"maxLength": 50
},
"billingCountry": {
"type": "string",
"description": "Country of registration, ISO 3166",
"maxLength": 50
},
"mailingAddress": {
"type": "string",
"description": "Physical location address",
"maxLength": 50
},
"mailingPostalCode": {
"type": "string",
"description": "Physical location postal code",
"maxLength": 50
},
"mailingCity": {
"type": "string",
"description": "Physical location city",
"maxLength": 50
},
"mailingState": {
"type": "string",
"description": "Physical location state",
"maxLength": 50
},
"mailingCountry": {
"type": "string",
"description": "Country of physical location, ISO 3166",
"maxLength": 50
},
"businessAddress": {
"type": "string",
"description": "Business location address",
"maxLength": 50
},
"businessPostalCode": {
"type": "string",
"description": "Business location postal code",
"maxLength": 50
},
"businessCity": {
"type": "string",
"description": "Business location city",
"maxLength": 50
},
"businessState": {
"type": "string",
"description": "Business location state",
"maxLength": 50
},
"businessCountry": {
"type": "string",
"description": "Country of business location, ISO 3166",
"maxLength": 50
},
"phone": {
"type": "string",
"description": "Vendor phon",
"maxLength": 50
},
"fax": {
"type": "string",
"description": "Vendor fax",
"maxLength": 50
},
"taxIdNumber": {
"type": "string",
"description": "Vendor tax number",
"maxLength": 50
},
"branch": {
"type": "string",
"description": "Vendor branch of operation",
"maxLength": 50
},
"mcc": {
"type": "integer",
"description": "Vendor category code (ISO 18245)"
},
"products": {
"type": "string",
"description": "Vendor products description",
"maxLength": 50
},
"license": {
"type": "string",
"description": "License ID of the vendor required in case MCC is within specific values",
"maxLength": 50
},
"licenseGeolocation": {
"type": "string",
"description": "Country of license applicability, ISO 3166",
"maxLength": 50
},
"webUrl": {
"type": "string",
"description": "Vendor website UR",
"maxLength": 50
},
"contractingParty": {
"type": "string",
"description": "Vendor contracting party name",
"maxLength": 50
},
"signingPerson": {
"type": "string",
"description": "Signing person",
"maxLength": 50
},
"technicalContact": {
"type": "string",
"description": "Technical contact",
"maxLength": 50
},
"technicalEmail": {
"type": "string",
"description": "Email of technical contact",
"maxLength": 50
},
"technicalPhone": {
"type": "string",
"description": "Phone number of technical contact",
"maxLength": 50
},
"ecommerceUrl": {
"type": "string",
"description": "URL of the shop where consumers are purchasing goods and services",
"maxLength": 50
},
"ipAddress": {
"type": "string",
"description": "Vendor IP address",
"maxLength": 50
},
"billingDescriptor": {
"type": "string",
"description": "Billing descriptor to be used in the transactions description as vendor billing descriptor",
"maxLength": 50
},
"beneficiaryName": {
"type": "string",
"description": "Name of primary beneficial owner of contracting party",
"maxLength": 50
},
"beneficiaryDOB": {
"type": "string",
"description": "Vendor beneficiary date of birth",
"format": "date"
},
"beneficiaryEquityOwnership": {
"type": "string",
"description": "Vendor beneficiary equity ownership, in percent",
"maxLength": 50
},
"beneficiaryAddress": {
"type": "string",
"description": "Vendor beneficiary address",
"maxLength": 50
},
"beneficiaryCity": {
"type": "string",
"description": "Vendor beneficiary city",
"maxLength": 50
},
"beneficiaryState": {
"type": "string",
"description": "Vendor beneficiary state",
"maxLength": 50
},
"beneficiaryCountry": {
"type": "string",
"description": "Vendor beneficiary country, ISO 3166",
"maxLength": 50
},
"beneficiaryPhone": {
"type": "string",
"description": "Vendor beneficiary phone number",
"maxLength": 50
},
"beneficiaryIdDoc": {
"type": "string",
"description": "Vendor beneficiary ID document",
"maxLength": 50
},
"beneficiaryIdDocCountry": {
"type": "string",
"description": "Vendor beneficiary ID document issue country, ISO 3166",
"maxLength": 50
},
"beneficiaryCitizenship": {
"type": "string",
"description": "Vendor beneficiary citizenship, ISO 3166",
"maxLength": 50
},
"beneficiaryDrivingLicence": {
"type": "string",
"description": "Vendor beneficiary driving license",
"maxLength": 50
},
"deliveryLevel": {
"type": "integer",
"description": "The number of confirmations in the Bitcoin blockchain to wait for until the status Ready for Delivery is reached for a given vendor's transaction"
}
},
"required": [
"id",
"merchantId",
"email",
"company"
]
}
200
This method doesn’t return any information if successfully called. Please see the API error section for further details.
Headers
Content-Type: application/json;charset=UTF-8
Server: Apache-Coyote/1.1
X-Content-Type-Options: nosniff
X-XSS-Protection: 1; mode=block
X-Frame-Options: DENY
Date: Wed, 13 Jan 2016 22:17:35 GMT
Connection: close
Content-Length: 0