For AI agents: markdown of this page — /docs-content-en/entities/payments/get.md documentation index — /llms.txt

Get a payment

GET /v1/payments/:id

Returns a single payment by ID with all fields.

Parameters

Parameter Type Required Description
Parameterid (path) Typenumber Requiredyes DescriptionPayment ID. List: GET /v1/payments
Parameterselect (query) Typestring Requiredno DescriptionComma-separated response fields, for example id,sum,currency,paid. Without it, every field is returned. The id field is always returned. An unknown name does not cause an error: that field is absent from the response, and meta.warnings carries an UNKNOWN_SELECT_FIELD warning. Names come from Payment fields

Examples

curl — personal key

Terminal 
curl "https://vibecode.bitrix24.com/v1/payments/17" \
  -H "X-Api-Key: YOUR_API_KEY"

curl — OAuth application

Terminal 
curl "https://vibecode.bitrix24.com/v1/payments/17" \
  -H "X-Api-Key: YOUR_APP_KEY" \
  -H "Authorization: Bearer USER_SESSION_TOKEN"

JavaScript — personal key

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments/17', {
  headers: {
    'X-Api-Key': 'YOUR_API_KEY',
  },
})

const { success, data } = await res.json()
console.log('Payment:', data.sum, data.currency, '—', data.paySystemName)

JavaScript — OAuth application

javascript 
const res = await fetch('https://vibecode.bitrix24.com/v1/payments/17', {
  headers: {
    'X-Api-Key': 'YOUR_APP_KEY',
    'Authorization': 'Bearer USER_SESSION_TOKEN',
  },
})

const { success, data } = await res.json()

Response fields

Field Type Description
Fieldsuccess Typeboolean DescriptionAlways true on success
Fielddata Typeobject DescriptionPayment object. All its fields are listed below
Fielddata.id Typenumber DescriptionPayment ID
Fielddata.accountNumber Typestring DescriptionSequential payment number on the Bitrix24 account
Fielddata.orderId Typenumber DescriptionOrder ID. List: GET /v1/orders
Fielddata.paySystemId Typenumber DescriptionPayment system ID. List: GET /v1/pay-systems
Fielddata.paySystemName Typestring DescriptionPayment system name
Fielddata.paySystemIsCash Typeboolean DescriptionWhether the payment system accepts cash (read-only)
Fielddata.paySystemXmlId Typestring DescriptionExternal payment system ID (read-only)
Fielddata.sum Typenumber DescriptionPayment amount
Fielddata.currency Typestring DescriptionPayment currency. List: GET /v1/currencies
Fielddata.paid Typeboolean DescriptionWhether the payment is marked as received
Fielddata.datePaid Typedatetime | null DescriptionDate the payment was marked as received. null if no date is set
Fielddata.dateBill Typedatetime DescriptionInvoice issue date
Fielddata.datePayBefore Typedatetime | null DescriptionPayment due date, with no meaningful time component. The time component in the response is always midnight in the Bitrix24 account time zone and has no separate meaning. null if not set
Fielddata.dateMarked Typedatetime | null DescriptionDate the payment was flagged as problematic (read-only). null if it is not flagged
Fielddata.dateResponsibleId Typedatetime | null DescriptionDate the responsible person was assigned (read-only). null if no responsible person is assigned
Fielddata.responsibleId Typenumber | null DescriptionResponsible employee. List: GET /v1/users. null if not assigned
Fielddata.comments Typestring | null DescriptionPayment comment. null if not set
Fielddata.xmlId Typestring DescriptionExternal ID
Fielddata.isReturn Typestring DescriptionRefund flag: "N" for a regular payment, "Y" for a refund, "P" for a partial refund
Fielddata.marked Typeboolean DescriptionWhether the payment is flagged as problematic
Fielddata.reasonMarked Typestring | null DescriptionReason for the flag. null if it is not flagged
Fielddata.empPaidId Typenumber | null DescriptionEmployee who marked the payment as received (read-only). List: GET /v1/users
Fielddata.empResponsibleId Typenumber | null DescriptionEmployee responsible for the payment (read-only). List: GET /v1/users
Fielddata.empMarkedId Typenumber | null DescriptionEmployee who set the flag (read-only). List: GET /v1/users
Fielddata.empReturnId Typenumber | null DescriptionEmployee who processed the refund (read-only). List: GET /v1/users
Fielddata.psStatus Typestring | null DescriptionPayment status reported by the payment system. null if the payment was not processed through a payment system
Fielddata.psStatusCode Typestring | null DescriptionStatus code from the payment system
Fielddata.psStatusDescription Typestring | null DescriptionStatus description from the payment system
Fielddata.psStatusMessage Typestring | null DescriptionMessage from the payment system
Fielddata.psSum Typenumber | null DescriptionPayment amount reported by the payment gateway
Fielddata.psCurrency Typestring | null DescriptionPayment currency reported by the payment gateway
Fielddata.psResponseDate Typedatetime | null DescriptionPayment gateway response date
Fielddata.psInvoiceId Typestring | null DescriptionInvoice ID on the payment gateway side
Fielddata.payVoucherNum Typestring | null DescriptionPayment order number. null if there is no payment order
Fielddata.payVoucherDate Typedatetime | null DescriptionPayment order date. null if there is no payment order
Fielddata.payReturnNum Typestring | null DescriptionRefund document number. null if there has been no refund
Fielddata.payReturnDate Typedatetime | null DescriptionRefund date. null if there has been no refund
Fielddata.payReturnComment Typestring | null DescriptionRefund comment. null if there has been no refund
Fielddata.priceCod Typenumber DescriptionCash on delivery amount. 0 if no cash on delivery amount is set
Fielddata.companyId Typenumber | null DescriptionPayer company from CRM. List: GET /v1/companies. null if not set
Fielddata.externalPayment Typeboolean DescriptionPayment was created in an external system
Fielddata.id1c Typestring | null DescriptionPayment ID in ERP. null if the payment is not synchronized with ERP
Fielddata.version1c Typestring | null DescriptionPayment version in ERP. null if the payment is not synchronized with ERP
Fielddata.updated1c Typeboolean DescriptionWhether the payment was updated through ERP
Fieldmeta.warnings Typearray DescriptionWarnings about unknown names in select, with code, message, and field. Only included when warnings exist

For the full list of fields with links to ID sources, see Payment fields.

Response example

JSON 
{
  "success": true,
  "data": {
    "id": 17,
    "accountNumber": "19/1",
    "orderId": 19,
    "paySystemId": 11,
    "paySystemName": "Cash",
    "paySystemIsCash": true,
    "paySystemXmlId": "bx_61372545d32ae",
    "sum": 0,
    "currency": "USD",
    "paid": false,
    "datePaid": "2020-05-14T20:00:00.000Z",
    "dateBill": "2020-05-14T20:00:00.000Z",
    "datePayBefore": null,
    "dateMarked": null,
    "dateResponsibleId": "2020-05-15T12:08:16.000Z",
    "responsibleId": 1,
    "empPaidId": null,
    "empResponsibleId": 1,
    "empMarkedId": null,
    "empReturnId": null,
    "comments": null,
    "reasonMarked": null,
    "xmlId": "bx_5ebe943aacfa0",
    "id1c": null,
    "version1c": null,
    "updated1c": false,
    "externalPayment": false,
    "isReturn": "N",
    "marked": false,
    "priceCod": 0,
    "companyId": null,
    "payReturnNum": null,
    "payReturnDate": null,
    "payReturnComment": null,
    "payVoucherNum": null,
    "payVoucherDate": null,
    "psStatus": null,
    "psStatusCode": null,
    "psStatusDescription": null,
    "psStatusMessage": null,
    "psSum": null,
    "psCurrency": null,
    "psInvoiceId": null,
    "psResponseDate": null
  }
}

Error response example

404 — payment not found:

JSON 
{
  "success": false,
  "error": {
    "code": "ENTITY_NOT_FOUND",
    "message": "payment is not exists"
  }
}

Errors

HTTP Code Description
HTTP404 CodeENTITY_NOT_FOUND DescriptionNo payment with this ID was found
HTTP403 CodeSCOPE_DENIED DescriptionThe API key does not have the sale scope
HTTP401 CodeTOKEN_MISSING DescriptionThe API key has no configured tokens

For the full list of common API errors, see Errors.

See also