Create referenced refund

Browse API reference

POST/bank-transfer-payments/{paymentId}/refundrefundBankTransferPayment

Use this method to refund a bank transfer payment that is in a closed batch.

To refund a bank transfer payment, you need its paymentId. Our gateway returned the paymentId in the response of the Create Payment method.

Note: If you don’t have the paymentId, use our List Payments method to search for the bank transfer payment.

If your refund is successful, our gateway returns the payment amount to the customer's account.

Things to consider

If the merchant refunds a bank transfer payment that is in an open batch, our gateway reverses the bank transfer payment.
Some merchants can run unreferenced refunds, which means that they don’t need a paymentId to return an amount to a customer. For more information about how to run an unreferenced refund, go to Create Refund.

Parameters

Name	In	Type	Description
`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.
`paymentId`Required	path	`string`	Unique identifier that our gateway assigned to the payment.

Request body

application/json · required

Field Edit request inputs →

amountintegerint64required
Total amount of the refund. The value is in the currency's lowest denomination, for example, cents.
descriptionstringrequired
Description of the refund.1–100 chars

Responses

Successful request. We refunded the payment.

200 OK · application/json

{
  "bankAccount": {
    "accountNumber": "****7890",
    "institutionNumber": "543",
    "nameOnAccount": "Sarah Hazel Hopper",
    "secureToken": {
      "customerName": "Sarah Hopper",
      "link": {
        "href": "https://api.payroc.com/v1/processing-terminals/1234001/secure-tokens/MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
        "method": "GET",
        "rel": "self"
      },
      "secureTokenId": "MREF_abc1de23-f4a5-6789-bcd0-12e345678901fa",
      "status": "notValidated",
      "token": "296753123456"
    },
    "transitNumber": "76543",
    "type": "pad"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "abc123"
    }
  ],
  "customer": {
    "contactMethods": [
      {
        "type": "email",
        "value": "sarah.hopper@example.com"
      }
    ],
    "notificationLanguage": "en"
  },
  "order": {
    "amount": 4999,
    "breakdown": {
      "subtotal": 4347,
      "taxes": [
        {
          "amount": 217,
          "name": "Sales Tax",
          "rate": 5
        }
      ],
      "tip": {
        "amount": 435,
        "percentage": 10,
        "type": "percentage"
      }
    },
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Refund for order OrderRef6543",
    "orderId": "OrderRef6543"
  },
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "transactionResult": {
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "status": "reversal",
    "type": "payment"
  }
}

Response schema · 80 of 111 fields

bankAccountobjectrequired
Polymorphic object that contains bank account information. The value of the type field determines which variant you should use: ach Automated Clearing House (ACH) details pad Pre-authorized debit (PAD) details
- achobject
  Object that contains the customer's account details.
  - accountNumberstringrequired
    Customer's bank account number. We mask all digits except the last four digits.4–17 chars
  - nameOnAccountstringrequired
    Customer's name.1–50 chars
  - routingNumberstringrequired
    Routing number of the customer’s account. Note: In responses, our gateway shows only the last four digits of the account's routing number, for example, *****4162.9–9 chars
  - secCodestring
    Indicates the type of authorization for the transaction. Note: The field is mandatory for ACH secure token. web – Online transaction. tel – Telephone transaction. ccd – Corporate credit or debit entry for a business bank account. ppd – Pre-arranged transaction.webtelccdppd
  - secureTokenobject
    Object that contains information about the secure token.+8 more fields at deeper levels — see the full spec
  - typestringrequired
    ach
- padobject
  Object that contains the customer's account details.
  - accountNumberstringrequired
    Customer's bank account number. We mask all digits except the last four digits.7–12 chars
  - institutionNumberstringrequired
    Three-digit code that represents the customer's bank.3–3 chars
  - nameOnAccountstringrequired
    Customer's name.1–29 chars
  - secureTokenobject
    Object that contains information about the secure token.+8 more fields at deeper levels — see the full spec
  - transitNumberstringrequired
    Five-digit code that represents the customer's banking branch.5–5 chars
  - typestringrequired
    pad
customFieldsobject[]
Array of customField objects.
- namestringrequired
  Name of the custom field.1–56 chars
- valuestringrequired
  Value for the custom field.1–100 chars
customerobject
Object that contains information about the customer.
- 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
- notificationLanguagestringiso-639-1
  Customer's preferred notification language. This code follows the ISO 639-1 standard.2–2 charsenfr
orderobjectrequired
Object that contains information about the transaction.
- breakdownobject
  Object that contains information about the transaction.
  - taxesobject[]
    Array of tax objects.+3 more fields at deeper levels — see the full spec
  - subtotalintegerint64required
    Total amount of the transaction before tax and tip. The value is in the currency's lowest denomination, for example, cents.
  - tipobject
    Object that contains information about the tip.+4 more fields at deeper levels — see the full spec
- 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
- dateTimestringdate-time
  Date and time that the processor processed the transaction. Our gateway returns this value in the ISO 8601 format.
- descriptionstring
  Description of the transaction.0–1024 chars
- orderIdstringrequired
  Unique identifier that the merchant assigns to the transaction.1–24 chars
paymentIdstringrequired
Unique identifier that we assigned to the payment.10–10 chars
processingTerminalIdstringrequired
Unique identifier that we assigned to the terminal.4–50 chars
refundsobject[]
List of refunds issued against the payment.
- amountintegerint64required
  Amount of the refund. This 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
- dateTimestringdate-timerequired
  Date and time that the refund was processed.
- 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.
- refundIdstringrequired
  Unique identifier of the refund.10–10 chars
- responseCodestringrequired
  Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
- responseMessagestringrequired
  Description of the response from the processor.1–48 chars
- statusstringrequired
  Current status of the refund.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
representmentobject
Object that contains information about a payment.
- amountintegerint64required
  Amount of the payment. This 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
- dateTimestringdate-timerequired
  Date and time that the payment was processed.
- 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.
- paymentIdstringrequired
  Unique identifier of the payment.10–10 chars
- responseCodestringrequired
  Response from the processor. A The processor approved the transaction. D The processor declined the transaction. E The processor received the transaction but will process the transaction later. P The processor authorized a portion of the original amount of the transaction. R The issuer declined the transaction and indicated that the customer should contact their bank. C The issuer declined the transaction and indicated that the merchant should keep the card as it was reported lost or stolen.ADEPRC
- responseMessagestring
  Response description from the processor.1–48 chars
- statusstringrequired
  Current status of the payment.readypendingdeclinedcompletereferralpickupreversalreturned+3 more
returnsobject[]
List of returns issued against the payment.
- closedbooleanrequired
  Indicates whether the merchant accepted an alternative payment method to complete the payment.
- datestringdaterequired
  The date that the check was returned.
- 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.
- paymentIdstringrequired
  Unique identifier that our gateway assigned to the payment.10–10 chars
- representedbooleanrequired
  Indicates whether the return has been re-presented.
- returnCodestringrequired
  The NACHA return code.
- returnReasonstringrequired
  The reason why the check was returned.
transactionResultobjectrequired
Object that contains information about the transaction.
- authorizedAmountintegerint64
  Amount of the transaction. Note: The amount is negative for a refund.
- currencystring
  Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
- processorResponseCodestring
  Original response code that the processor sent.
- responseCodestringrequired
  Response from the processor. A The processor approved the transaction. D The processor declined the transaction.
- responseMessagestring
  Description of the response from the processor.1–48 chars
- statusstringrequired
  Status of the transaction. The value is one of the following: ready Successful transaction. We added the payment to the open batch. pending Successful transaction. We added the payment to the open batch, but we don’t collect the funds when the batch is closed. declined Unsuccessful transaction. The customer's bank declined the transfer. complete Successful transaction. The funds have moved to the merchant’s bank account. admin Transaction under review. We have flagged an issue with the transaction. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. returned Unsuccessful transaction. Automated clearing house (ACH) returned the transaction due to an error. For more information about the error, view the returns object.readypendingdeclinedcompleteadminreversalreturned
- typestringrequired
  Type of transaction.paymentrefundunreferencedRefundaccountVerification

Validation error

400 Bad Request · application/problem+json

{
  "detail": "'Idempotency-Key' is already in use against a different request",
  "status": 409,
  "title": "Idempotency-Key in use",
  "type": "https://docs.payroc.com/api/errors#idempotency-key-in-use"
}

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-a-bank-transfer-payment

Create referenced refund

Browse API reference

Parameters

Request body

Responses

Used in workflows

Menu

Sign out

Talk to an engineer