API. Overview¶
API section documents the implementation of the RESTful API for payment acceptance within the Internet Acquiring product.
Interaction Format¶
The Payment Acceptance API is based on the REST architecture, where data and methods are considered as resources accessed via calling Uniform Resource Identifiers (URIs).
Interaction with the API is conducted over a secure protocol (HTTPS). Only HTTPS requests are supported; HTTP requests over an unencrypted channel are not supported. Data in requests is transmitted in JSON format encoded in UTF-8, and responses also return data in JSON format encoded in UTF-8.
API methods ensure logical idempotence, meaning multiple calls to a method are equivalent to a single call. However, the server response may change; for example, the account balance may vary from request to request.
API URL¶
The constant part of the URL to make API calls:
https://b2b-api.qiwi.com/partner/payin/
Authorization¶
Requests authorization is performed via OAuth 2.0 standard in accordance with RFC 6750. Always put API access key value into Authorization HTTP-header as
Bearer <API Key>
Request with authorization example:
curl -X PUT \
https://b2b-api.qiwi.com/partner/payin/v1/sites/{site_id}/payments/{payment_id} \
--oauth2-bearer <Ключ API>
Authorization header example:
Authorization: Bearer 5c4b25xx93aa435d9cb8cd17480356f9
Value Formats¶
3D-Secure Data¶
Data for bank card authentication via 3DS and 3DS2.0 protocols is transmitted in threeDS object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| pareq | Yes | string | Authentication message to send to issuer bank ACS via customer browser.Returned in response to the following requests: “Retrieving Invoice Information”, “Creating a Payment”, “Completing Customer Authentication” and “Card Verification“ |
| acsUrl | Yes | string | Issuer bank ACS URL for customer redirect.Returned in response to the following requests: “Retrieving Invoice Information”, “Creating a Payment”, “Completing Customer Authentication” and “Card Verification“ |
| pares | Yes | string | Result of customer authentication received after return from issuer bank ACS.Transmitted in the following request: “Completing Customer Authentication”, and returns in the response to the “Complete 3DS on Card Verification” request |
Additional Information for the Operation¶
The information is transmitted in customFields object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| auto_capture | Yes | boolean | Indicates that payment was made with auto capture.Returned in response to the requests: “Retrieving invoice information”, “Retrieving a list of invoice payments“ |
| contract_id | No | string | Client’s contract ID for MFO data transfer.Returned in response to the “Creating an invoice” request |
| invoice_callback_url | No | string(256) | Notification URL.Returned in response to the “Creating an invoice” request |
| invoice_creation_type | Yes | string | Type of the interface used for creating the invoice.Returned in response to the requests: “Retrieving invoice information”, “Retrieving a list of invoice payments“ |
| themeCode | No | string(256) | Style code to apply on the Payment Form..Returned in response to the “Creating an invoice” request |
| cf1 | No | string(256) | Additional information that supplements the operation data |
| cf2 | No | string(256) | Additional information that supplements the operation data |
| cf3 | No | string(256) | Additional information that supplements the operation data |
| cf4 | No | string(256) | Additional information that supplements the operation data |
| cf5 | No | string(256) | Additional information that supplements the operation data |
Address¶
The data is transmitted in address object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| country | No | string(1000) | Country |
| city | No | string(1000) | City |
| region | No | string(1000) | District, region, state |
| details | No | string(1000) | Street address |
Bank Card Data¶
Bank card data is transmitted in cardData object of the “Card verification” request.
| Parameter | Required | Format | Description |
|---|---|---|---|
| pan | Yes | string(19) | PAN |
| expiryDate | Yes | string(5) | Card validity period in MM/YY format |
| cvv2 | Yes | string(4) | CVV2/CVC2 on the card |
| holderName | No | string(26) | Cardholder name as stated on the card (Latin letters) |
| cardTokenPaymentType | No | string | A parameter for correct processing of transactions in payment systems for operations with saved cards.Possible values: FIRST_PAYMENT — if the card will be saved on your side with this operation |
Client’s Device¶
The information on the client’s device is transferred in deviceData object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| ip | Yes | string(39) | IP address |
| userAgent | No | string(256) | Browser |
| screenResolution | No | string(64) | Screen resolution |
| fingerprint | No | string(64) | Unique identifier of the client’s device |
| datetime | No | string(26) | Client’s local time |
| timeOnPage | No | integer | Time spent on a web page |
Customer¶
The customer information is transmitted in customer object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| account | Yes | string(64) | Customer’s identifier in the merchant’s system |
| No | string(1000) | City | |
| phone | No | string(1000) | District, region, state |
| address | No | object | Street address |
| lastName | No | string | Client’s last name for MFO data transfer |
| firstName | No | string | Client’s first name for MFO data transfer |
| middleName | No | string | Client’s patronymic for MFO data transfer |
Data for Payment Token Generation¶
Data for payment token generation is transmitted in tokenizationData object of the “Card Verification” request.
| Parameter | Required | Format | Description |
|---|---|---|---|
| account | Yes | string(64) | Unique customer identifier in the merchant’s system |
Date and Time¶
The API accepts and returns date and time in ISO 8601 format with time zone. Example: 2023-08-13T14:30:00+03:00
Field Validation Error Description¶
The description of a field validation error is transmitted in cause object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| fieldName: [value] | No | array of strings | fieldName — name of the specific field,[value] — validation errors for this field |
FPS Payment Token¶
Information on the FPS payment token. The information is returned in token object in the response to the request for creating a QR code for FPS, if the token creation is requested.
| Parameter | Required | Format | Description |
|---|---|---|---|
| status | Yes | string | FPS token creation status (possible values: IN_PROGRESS, CREATED, REJECTED) |
| expiredDate | Yes | string | FPS payment token expiration date |
| value | No | string | FPS payment token data |
| rejectReason | No | string | Operation rejection reason |
| bankMemberId | No | string | Client’s bank identifier in FPS |
Information on the First Transaction¶
Information about the transaction with which the card was saved. The information is transmitted in paymentMethod.firstTransaction object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| paymentId | No | string | Unique payment identifier in the merchant’s system |
| trnId | No | string | Unique payment identifier in the National Payment Card System’s system |
Invoice Payments List¶
A list of payments for an invoice is transmitted as a payments array that contains oblects with parameters described in the table.
| Parameter | Required | Format | Description |
|---|---|---|---|
| paymentId | Yes | string | Payment identifier |
| billId | Yes | string | Invoice identifier |
| createdDateTime | Yes | string | Invoice creation date and time |
| amount | Yes | object | Operation amount |
| capturedAmount | Yes | object | Captured amount |
| refundedAmount | Yes | object | Refunded amount |
| paymentMethod | Yes | object | Payment method |
| status | Yes | object | Payment status |
| customer | No | object | Customer information: account, email, phone, address |
| requirements | No | object | Requirements for additional authentication of the customer received with the payment operation |
| comment | No | string | Payment commentary |
| customFields | No | object | Fields with additional information that supplement the operation data: auto_capture, invoice_creation_type, etc |
Invoice Status¶
The invoice status is transmitted in status field in the response to “Retrieving Invoice Information” request.
| Parameter | Required | Format | Description |
|---|---|---|---|
| value | Yes | string | Invoice status |
| changedDateTime | Yes | string | Date of the invoice status change |
| reason | No | string | Invoice rejection reason. Please see the list of possible reasons in API Errors |
| reasonMessage | No | string | Rejection reason details |
Operation Amount¶
Operation amount is transmitted in amount, capturedAmount, refundedAmount depending on operation type.
| Parameter | Required | Format | Description |
|---|---|---|---|
| value | Yes | number(6.2) | Operation amount, rounded down to two decimal places |
| currency | Yes | string(3) | Currency code according to ISO 4217. |
Operation Status¶
Operation status is transmitted in status field.
| Parameter | Required | Format | Description |
|---|---|---|---|
| value | Yes | string | Operation status value |
| changedDateTime | Yes | string | Date of the operation status change |
| reason | No | string | Rejection reason. Please see the list of possible reasons in API Errors |
| reasonMessage | No | string | Rejection reason details |
| psErrorCode | No | string | Operation rejection reason received from the payment system. Please see the list of possible reasons in error detail codes list |
Payment Card¶
Information on the card that was used for payment.
| Parameter | Required | Format | Description |
|---|---|---|---|
| issuingCountry | No | string(3) | Issuer country code |
| issuingBank | No | string | Issuer name |
| paymentSystem | No | string | Card’s payment system type |
| fundingSource | No | string | Card’s type (debit/credit/…) |
| paymentSystemProduct | No | string | Card category |
Payment Method¶
Payment method data is transferred in paymentMethod object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| type | Yes | string | Payment method type. CARD — bank card TOKEN — payment token |
| pan | No | string(19) | Bank card number.Only for type=CARD |
| maskedPan | No | string(19) | Bank card number, masked.Only for type=CARD |
| expiryDate | No | string(5) | Bank card expiration date in MM/YY format.Only for type=CARD |
| cvv2 | No | string(4) | CVV2/CVC2 on the bank card.Only for type=CARD |
| holderName | No | string(26) | Cardholder name (Latin letters).Only for type=CARD |
| paymentToken | No | string | Payment token.Only for type=TOKEN |
| cardTokenPaymentType | No | string | Parameter for correct processing of transactions in the payment systems (for operations with saved tokenized cards). Possible values |
| firstTransaction | No | object | Identifier for the transaction with which the card was saved.For type=CARD, TOKEN |
Payment Recipient¶
The payment recipient information is transmitted in receiverData object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| pan | No | string(19) | Card number of the money transfer recipient. Specified for money transfer operations |
| phone | No | string(15) | Recipient’s phone number. Specified when replenishing the phone. |
| bankAccount | No | string(20) | Recipient’s account number. Specified for money transfer operations |
| bic | No | string(9) | BIC of the credit institution of the recipient. Specified for money transfer operations |
Payment Token¶
Information on the payment token for the bank card. The information is returned in createdToken object in the response to the request for creating a payment, if the token creation is requested; the request for retrieving a list of invoice payments, if the token was used for payment, etc.
| Parameter | Required | Format | Description |
|---|---|---|---|
| token | Yes | string | Payment token for the card |
| expiredDate | Yes | string | Payment token expiration date |
| name | No | string | Masked number of the tokenized card |
QR Code Image Parameters¶
QR code image parameters are transmitted in qrCode.image object in the Creating a QR code for FPS request and response.
| Parameter | Required | Format | Description |
|---|---|---|---|
| content | Yes | string | QR code image (Base64-encoded).Transmitted only in the response |
| mediaType | No | string | Image type. Possible values: image/png, image/svg+xml.Can be transmitted in request and response |
| width | No | number | Image width in pixels. Integer in 200 - 1000 range. Can be transmitted in request and response |
| height | No | number | Image height in pixels. Integer in 200 - 1000 range. Can be transmitted in request and response |
QR Code Parameters¶
QR code parameters are transmitted in qrCode object in the Creating a QR code for FPS request and response.
| Parameter | Required | Format | Description |
|---|---|---|---|
| type | Yes | string | QR code type Transmitted in request and response |
| status | Yes | string | Current status of the QR code Transmitted in response |
| payload | No | string | QR code data Can be transmitted in response |
| ttl | No | number | QR code validity period in minutes.Only for type=DYNAMIC. By default a dynamic QR code is valid for 72 hours, and deactivates when this period expires. Can be transmitted in request and response |
| image | No | object | QR code image parameters Can be transmitted in request and response |
| declineReason | No | string | Reason for transaction rejection Can be transmitted in response |
QR Code Payment Information¶
QR code payment information is transmitted in payment object of the response to the FPS QR code creation request (only for type=DYNAMIC).
| Parameter | Required | Format | Description |
|---|---|---|---|
| paymentUid | Yes | string | Payment identifier. This identifier is used in API refund method |
| paymentStatus | Yes | string | Payment status |
| declineReason | No | string | Operation rejection reason |
QR Code Refunds Data¶
QR code refunds data is transmitted in refunds object of the response to the FPS QR code creation request (only for type=DYNAMIC).
| Parameter | Required | Format | Description |
|---|---|---|---|
| refundUid | Yes | string | Refund identifier |
| refundStatus | Yes | string | Refund status |
| gatewayRefundId | No | string | Refund identifier from gateway |
| declineReason | No | string | Operation rejection reason |
Requirements for Additional Authentication¶
The requirements for additional authentication of the customer are transmitted in payments.requirements object of the response to the following requests: “Retrieving Invoice Information”, “Creating a Payment”, “Completing Customer Authentication”.
| Parameter | Required | Format | Description |
|---|---|---|---|
| threeDS | Yes | object | Data for bank card authentication via 3DS and 3DS2.0 protocols |
Saved Card Information¶
If a saved card was used for the payment, the card information is transmitted in credentialOnFile object.
| Parameter | Required | Format | Description |
|---|---|---|---|
| type | No | string | TYpe of the payment operation using a saved card |
| trn | No | string | Identifier of a transaction in which the card was saved |