Submit refund instruction

Browse API reference

POST/devices/{serialNumber}/refund-instructionssendRefundInstruction

Use this method to submit an instruction request to initiate a refund on a payment device.

In the request, include the refund amount and currency.

If the request is successful, our gateway returns information about the refund instruction and a refundInstructionId, which you need for the following methods:

Retrieve refund instruction - View the details of the refund instruction.
Cancel refund instruction - Cancel the refund instruction.

Parameters

Name	In	Type	Description
`serialNumber`Required	path	`string`	Serial number that identifies the merchant’s payment device.
`Idempotency-Key`Required	header	`string`	Unique identifier that you generate for each request. You must use the UUID v4 format for the identifier. For more information about the idempotency key, go to Idempotency.

Request body

application/json · required

Field Edit request inputs →

customerobject
Object that contains the customer's contact details and address information. Contains parameters required for Level 2, Level 3, and CEDP transactions.
- billingAddressobject
  Object that contains information about the address.
  - address1stringrequired
    Address line 1.≤ 150 chars
  - address2string
    Address line 2.≤ 150 chars
  - address3string
    Address line 3.≤ 150 chars
  - citystringrequired
    City.≤ 50 chars
  - countrystringrequired
    Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
  - postalCodestringrequired
    Zip code or postal code.≤ 10 chars
  - statestringrequired
    Name of the state or state abbreviation.≤ 50 chars
- contactMethodsobject[]
  Array of polymorphic objects, which contain contact information. The value of the type parameter determines which variant you should use: email Email address phone Phone number mobile Mobile number fax Fax number
  - emailobject
    +2 more fields at deeper levels — see the full spec
  - phoneobject
    +2 more fields at deeper levels — see the full spec
  - mobileobject
    +2 more fields at deeper levels — see the full spec
  - faxobject
    +2 more fields at deeper levels — see the full spec
- dateOfBirthstringdate
  Customer's date of birth. The format for this value is YYYY-MM-DD.
- firstNamestring
  Customer's first name.0–60 chars
- lastNamestring
  Customer's last name.0–60 chars
- notificationLanguagestringiso-639-1
  Language that the customer uses for notifications. This code follows the ISO 639-1 alpha-2 standard.2–2 charsenfr
- referenceNumberstring
  Identifier of the transaction, also known as a customer code. For requests, you must send a value for referenceNumber if the customer provides one. Required for Level 2, Level 3, and CEDP transactions.0–48 chars
- shippingAddressobject
  Object that contains information about the customer and their shipping address. Contains parameters required for Level 3 and CEDP transactions.
  - addressobject
    Object that contains information about the address.+7 more fields at deeper levels — see the full spec
  - recipientNamestring
    Recipient's name. Required for Level 3 and CEDP transactions.0–50 chars
customizationOptionsobject
Object that contains available options to customize certain aspects of an instruction.
- closedLoopOptionsobject
  Polymorphic object that indicates the type of closed-loop card that the merchant accepts.
  - option 1object
    +1 more fields at deeper levels — see the full spec
- ebtDetailsobject
  Object that contains information about the Electronic Benefit Transfer (EBT) transaction.
  - benefitCategorystringrequired
    Indicates if the balance relates to an EBT Cash account or an EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
  - withdrawalboolean
    Indicates whether the customer wants to withdraw cash. Note: Cash withdrawals are available only from EBT Cash accounts.
- entryMethodstring
  Indicates how you want the device to capture the card details. deviceRead Device prompts the cardholder to tap, swipe, or insert their card. manualEntry Device prompts the merchant or cardholder to manually enter card details. deviceReadOrManualEntry Device prompts the cardholder to tap, swipe, or insert their card. The device also displays an option for the merchant or cardholder to manually enter card details.deviceReadmanualEntrydeviceReadOrManualEntry
ipAddressobject
Object that contains the IP address of the device that sent the request.
- typestringrequired
  Internet protocol version of the IP address.ipv4ipv6
- valuestringrequired
  IP address of the device.
operatorstring
Operator who initiated the request.0–50 chars
orderobjectrequired
Object that contains information about the refund.
- amountintegerint64required
  Total amount of the transaction. The value is in the currency’s lowest denomination, for example, cents.
- currencystringrequired
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- descriptionstringrequired
  Description of the transaction.0–1024 chars
- orderIdstringrequired
  Unique identifier that the merchant assigns to the transaction.1–24 chars
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars

Responses

Successful request. We accepted the refund instruction.

202 Accepted · application/json

{
  "link": {
    "href": "https://api.payroc.com/v1/refund-instructions/a37439165d134678a9100ebba3b29597",
    "method": "GET",
    "rel": "self"
  },
  "refundInstructionId": "a37439165d134678a9100ebba3b29597",
  "status": "inProgress"
}

Response schema · 7 fields

errorMessagestring
Description of the error that caused the instruction to fail. Note: We return this field only if the status is failure.
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusstringrequired
Indicates the current status of the instruction. canceled – The instruction was canceled before it was completed. completed – The instruction has completed. Use the link object to check the resource. failure – The instruction failed. Check the errorMessage field for more information. inProgress – The instruction is currently in progress.canceledcompletedfailureinProgress
refundInstructionIdstringrequired
Unique identifier that we assigned to the refund instruction.1–36 chars

Validation error

400 Bad Request · application/problem+json

{
  "detail": "An 'Idempotency-Key' must be supplied for this request",
  "status": 400,
  "title": "Idempotency-Key header missing",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-missing"
}

Response schema · 8 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Identity could not be verified

401 Unauthorized · application/problem+json

{
  "detail": "Your identity could not be verified",
  "status": 401,
  "title": "Not Authorized",
  "type": "https://docs.payroc.com/api/errors#not-authorized"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Do not have permissions to perform this action

403 Forbidden · application/problem+json

{
  "detail": "You do not have the required permissions to perform this action",
  "instance": "https://api.payroc.com/v1/exampleResource/3",
  "resource": "exampleResource",
  "status": 403,
  "title": "Forbidden",
  "type": "https://docs.payroc.com/api/errors#forbidden"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
instancestring
Resource path the action was attempted on
resourcestring
Resource the action was attempted on
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Resource not found

404 Not Found · application/problem+json

{
  "detail": "Resource not found",
  "resource": "(The Type of the Resource)",
  "status": 404,
  "title": "Not found",
  "type": "https://docs.payroc.com/api/errors#not-found"
}

Response schema · 5 fields

detailstringrequired
Explanation of the problem
resourcestring
Resource that was not found
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Not acceptable

406 Not Acceptable · application/problem+json

{
  "detail": "Resource does not support the representation requested",
  "status": 406,
  "title": "Not acceptable",
  "type": "https://docs.payroc.com/api/errors#not-acceptable"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Conflict

409 Conflict · application/problem+json

{
  "detail": "The resource you attempted to create already exists",
  "instance": "https://api.payroc.com/v1/merchant/12345",
  "status": 409,
  "title": "Resource already exists",
  "type": "https://docs.payroc.com/api/errors#resource-already-exists"
}

Response schema · 13 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- detailstring
  Short detail of the validation errors
- messagestring
  Error message
- parameterstring
  The parameter or field causing the issues
instancestring
Resource path to the existing resource
linkobject
Object that contains HATEOAS links for the resource.
- hrefstringrequired
  URL of the target resource.
- methodstringrequired
  HTTP method that you need to use with the target resource.
- relstringrequired
  Indicates the relationship between the current resource and the target resource.
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Unsupported media type

415 Unsupported Media Type · application/problem+json

{
  "detail": "You submitted a payload in an unsupported format",
  "status": 415,
  "title": "Unsupported media type",
  "type": "https://docs.payroc.com/api/errors#unsupported-media-type"
}

Response schema · 4 fields

detailstringrequired
Explanation of the problem
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

An error has occured

500 Internal Server Error · application/problem+json

{
  "detail": "We are unable to process your request at this time",
  "errors": [
    {
      "message": "Service offline"
    }
  ],
  "status": 500,
  "title": "Api error",
  "type": "https://docs.payroc.com/api/errors#api-error"
}

Response schema · 6 fields

detailstringrequired
Explanation of the problem
errorsobject[]
- messagestring
  Error message
statusintegerrequired
Http status code
titlestringrequired
Short description of the issue.
typestringrequired
URI reference identifying the problem type

Used in workflows

refund-on-a-device

Submit refund instruction

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer