Create a draft payment - ZEN transfers API

Endpoint is used to order payments. The paymentId parameter is returned in response, which is used in endpoints to get payment details or get payment confirmation in PDF.

Create a POST request

WARNING

Request header with Authorization parameter is obliged for all requests sent to ZEN.COM API. Authorization value is the apiKey parameter which is generated and provided by ZEN.COM to the Client. This key is unique to each Customer and should not be shared or used by third parties.

Create a POST request.

Body parameters

Parameter	Description	Type	Required	Validation
`accountId`	id of the account from which the payment is made	string ($uuid)	yes
`externalId`	id generated by the Customer - this parameter will protect the process against duplicate payments. If you send the same `externalId` with: (1) the same body will return 201 `result_code` `ALREADY_CREATED`; (2) a different body, 404 `EXTERNAL_ID_ALREADY_EXIST` will be returned	string	yes	regexp: '^[a-zA-Z0-9?&:-/=.,#]+$' min=1 max=128
`amount.value`	payment amount	number ($double)	yes	>0, not blank, currency precision
`amount.currency`	payment currency	string (ISO 4217 standard)	yes	min=3 max=3 not blank
`title`	title	string	yes	RegExp = a-zA-Z0-9À-ÿĀ-ſ/ \-?:(),.'"+\r\n\t min=1 max=140 not blank
`chargeType`	charge Type	enum `SHA`, `OUR`, `LOCAL`, `STANDARD`, `INSTANT`	according to the endpoint response GET/payments/v1.0/precalculation
`purposeCode`	the purpose for which the payment is made, required for BH, AE, CN countries	string	required for payments to AE, BH, CN countries, code list available for get using the endpoint GET/constans/v1.0/purpose-codes	min=3 max=3
`receiver.accountNumber`	receiver's account number	string	yes	regexp: [A-Z0-9]+ min=6 max=34
`receiver.type`	receiver type	enum `INDIVIDUAL`, `BUSINESS`	yes
`receiver.firstName`	receiver's first name	string	only required for type = `INDIVIDUAL`	RegExp = a-zA-ZÀ-ÿĀ-ſ ."'- min=1 max=70
`receiver.lastName`	receiver's last name	string	only required for type = `INDIVIDUAL`	RegExp = a-zA-ZÀ-ÿĀ-ſ ."'- min=1 max=70
`receiver.companyName`	receiver's company name	string	only required for type = `BUSINESS`	RegExp = a-zA-Z0-9À-ÿĀ-ſ/ \-?:(),.'"+ min=1 max=150
`receiver.bic`	bic	string	`bic` or `routingCode` required	min=7 max=11
`routingCodeType`	routing code type	enum `SORT_CODE`	required if `routingCode` exists	min=1 max=100
`receiver.routingCode`	routing code	string	`bic` or `routingCode` required	min=6 max=16
`receiver.address.city`	receiver's city	string	required if endpoint GET/payments/v1.0/precalculation will return SWIFT or LOCAL FULL ADDRESS in the `chargeTypesData.channel` field	RegExp = a-zA-Z0-9À-ÿĀ-ſ/ \-?:(),.'"+ min=1 max=50
`receiver.address.postCode`	receiver's post code	string (according to country code)	required if endpoint GET/payments/v1.0/precalculation will return SWIFT or LOCAL FULL ADDRESS in the `chargeTypesData.channel` field	min=1 max=50
`receiver.address.addressLine`	receiver's address	string	required if endpoint GET/payments/v1.0/precalculation will return SWIFT or LOCAL FULL ADDRESS in the `chargeTypesData.channel` field	RegExp = a-zA-Z0-9À-ÿĀ-ſ/ \-?:),.'"+\r\n\t min=1 max=140
`receiver.address.country`	receiver's country	string (two-letter ISO country code)	required if endpoint GET/payments/v1.0/precalculation will return SWIFT or LOCAL FULL ADDRESS in the `chargeTypesData.channel` field	min=2 max=2

💡

Example of JSON

Send the request

Send the POST request to:

test environment: https://api-services.zen-test.com/payments/v1.0/drafts

production environment: https://api-services.zen.com/payments/v1.0/drafts

Receive the ZEN.COM response

Receive the ZEN.COM response.

Parameters

Parameter	Description	Type	Nullable
`resultCode`	the field indicates whether the payment has been created or it is another call with the same parameters	enum `CREATED` (if the payment was created correctly the first time) / `ALREADY_CREATED` (if there is a duplicate request with the same externalId and body)	no
`paymentId`	payment id	string ($uuid)	no

💡

Example response

{
  "resultCode": "CREATED",
  "paymentId": "3fa85f64-5717-4562-b3fc-2c963f66afa6"
}

Errors

HTTP code	Business code	Description
400	`VALIDATION_ERROR`	the data has not been validated
403	`FORBIDDEN`	no access to the resource
404	`ACCOUNT_NOT_FOUND`	no account with the specified accountId was found
409	`EXTERNAL_ID_ALREADY_EXIST`	the externalId provided has already been used for another payment
422	`INVALID_DATA`	incorrect data on the request
500	`INTERNAL_SERVER_ERROR`	server error, please contact ZEN

💡

Example error response

{
   "error":{
      "code":"INTERNAL_SERVER_ERROR",
      "message":"Unexpected error. Contact ZEN"
   }
}