Skip to content
payrocdevelopers

Create referenced refund

Browse API reference

POST/payments/{paymentId}/refundrefundPayment

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

To refund a 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 payment.

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

Things to consider

  • If the merchant refunds a payment that is in an open batch, our gateway reverses the 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

NameInTypeDescription
Idempotency-KeyRequiredheaderstring

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.

paymentIdRequiredpathstring

Unique identifier of the payment that the merchant wants to retrieve.

Request body

application/json · required
Field Edit request inputs →
  • amountintegerint64required
    Amount of the payment that the merchant wants to refund. The value is in the currency’s lowest denomination, for example, cents.
  • descriptionstringrequired
    Reason for the refund.1–100 chars
  • operatorstring
    Operator who refunded the payment.0–50 chars

Responses

Successful request. We refunded the payment.

200 OK · application/json
{
  "card": {
    "cardNumber": "453985******7062",
    "entryMethod": "keyed",
    "expiryDate": "1230",
    "securityChecks": {
      "avsResult": "Y",
      "cvvResult": "M"
    },
    "type": "MasterCard"
  },
  "customFields": [
    {
      "name": "yourCustomField",
      "value": "acb123"
    }
  ],
  "customer": {
    "billingAddress": {
      "address1": "1 Example Ave.",
      "address2": "Example Address Line 2",
      "address3": "Example Address Line 3",
      "city": "Chicago",
      "country": "US",
      "postalCode": "60056",
      "state": "Illinois"
    },
    "firstName": "Sarah",
    "lastName": "Hopper",
    "shippingAddress": {
      "address": {
        "address1": "1 Example Ave.",
        "address2": "Example Address Line 2",
        "address3": "Example Address Line 3",
        "city": "Chicago",
        "country": "US",
        "postalCode": "60056",
        "state": "Illinois"
      },
      "recipientName": "Sarah Hopper"
    }
  },
  "operator": "Jane",
  "order": {
    "amount": 4999,
    "currency": "USD",
    "dateTime": "2024-07-02T15:30:00Z",
    "description": "Large Pepperoni Pizza",
    "orderId": "OrderRef6543"
  },
  "paymentId": "M2MJOG6O2Y",
  "processingTerminalId": "1234001",
  "refunds": [
    {
      "amount": -4999,
      "currency": "USD",
      "dateTime": "2024-07-02T15:30:00Z",
      "link": {
        "href": "https://api.payroc.com/v1/refunds/BI77XQFQ05",
        "method": "GET",
        "rel": "self"
      },
      "refundId": "CD3HN88U9F",
      "responseCode": "A",
      "responseMessage": "Transaction refunded",
      "status": "ready"
    }
  ],
  "supportedOperations": [
    "refund"
  ],
  "transactionResult": {
    "approvalCode": "OK3",
    "authorizedAmount": 4999,
    "currency": "USD",
    "responseCode": "A",
    "responseMessage": "OK13",
    "status": "complete",
    "type": "sale"
  }
}
Response schema · 110 of 160 fields
  • cardobjectrequired
    Object that contains the details of the payment card.
    • balancesobject[]
      Array of cardBalance objects. Our gateway returns this array only when the customer uses an Electronic Benefit Transfer (EBT) card.
      • amountintegerint64required
        Current balance of the account. This value is in the currency's lowest denomination, for example, cents.
      • benefitCategorystringrequired
        Indicates if the balance relates to an EBT Cash account or EBT SNAP account. cash – EBT Cash foodStamp – EBT SNAPcashfoodStamp
      • currencystringrequired
        Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    • cardNumberstringrequired
      Card number. In the response, our gateway shows only the first six digits and the last four digits of the card number, for example, 500165******0000.12–19 chars
    • cardholderNamestring
      Cardholder’s name.1–50 chars
    • cardholderSignaturestring
      Cardholder’s signature.
    • emvTagsobject[]
      Array of emvTag objects.
      • hexstringrequired
        Hex code of the EMV tag.
      • valuestringrequired
        Value of the EMV tag.
    • entryMethodstringrequired
      Method that the device used to capture the card details.icckeyedswipedswipedFallbackcontactlessIcccontactlessMsr
    • expiryDatestringrequired
      Expiry date of the customer's card. The format is in MMYY.[0-9]{4}
    • secureTokenobject
      Object that contains information about the secure token.
      • customerNamestringrequired
        Customer's name.1–50 chars
      • linkobject
        Object that contains HATEOAS links for the resource.+3 more fields at deeper levels — see the full spec
      • secureTokenIdstringrequired
        Unique identifier that the merchant assigned to the secure token.1–200 chars
      • statusstringrequired
        Status of the customer's bank account. The processor performs a security check on the customer's bank account and returns the status of the account. Note: Depending on the merchant's account settings, this feature may be unavailable.notValidatedcvvValidatedvalidationFailedissueNumberValidatedcardNumberValidatedbankAccountValidated
      • tokenstringrequired
        Token that the merchant can use in future transactions to represent the customer's payment details. The token: Begins with the six-digit identification number 296753. Contains up to 12 digits. Contains a single check digit that we calculate using the Luhn algorithm.12–19 chars
    • securityChecksobject
      Object that contains information about card verification and security checks.
      • avsResultstring
        Indicates if the address that the customer provided in the request matches the address linked to the card. Y – The address in the request matches the address linked to the card. N – The address in the request doesn’t match the address linked to the card. A – The street address matches, but ZIP code or postal code doesn’t match. Z The ZIP code or postal code matches, but street address doesn’t match. U – The address information is unavailable. G – The issuer or card brand doesn’t support the Address Verification Service (AVS). R – The AVS is currently unavailable. Try again later. S – There was no AVS data in the request, or it was sent in the wrong format. F For UK addresses, the address in the request matches the address linked to the card. W – For US addresses, the nine-digit ZIP code or postal code in the request matches the address linked to the card but the street address doesn’t. X – For US addresses, the nine-digit ZIP code or postal code and the street address matches the address linked to the card. Note: Our gateway doesn’t automatically decline transactions when the address doesn’t match the address linked to the card, unless the merchant selects this setting in their account.YAZNURGS+3 more
      • cvvResultstring
        Indicates if the card verification value (CVV) that the customer provided in the request matches the CVV on the card. M – The CVV matches the card’s CVV. N – The CVV doesn’t match the card’s CVV. P – The CVV wasn’t processed. U – The CVV isn’t registered. Note: Our gateway doesn’t automatically decline transactions when the CVV doesn’t match the card’s CVV, unless the merchant selects this setting in their account.MNPU
    • typestringrequired
      Card brand of the card, for example, Visa.
  • 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 the customer's contact details and address information.
    • billingAddressobject
      Object that contains information about the address.
      • address1string
        Address line 1.≤ 150 chars
      • address2string
        Address line 2.≤ 150 chars
      • address3string
        Address line 3.≤ 150 chars
      • citystring
        City.≤ 50 chars
      • countrystring
        Two-digit country code for the country that the business operates in. The format follows the ISO-3166-1 standard.2–2 chars
      • postalCodestring
        Zip code or postal code.≤ 10 chars
      • statestring
        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.0–48 chars
    • shippingAddressobject
      Object that contains information about the customer and their shipping address.
      • addressobject
        Object that contains information about the address.+7 more fields at deeper levels — see the full spec
      • recipientNamestring
        Recipient's name.0–50 chars
  • operatorstring
    Operator who initiated the request.0–50 chars
  • orderobjectrequired
    Object that contains information about the payment.
    • breakdownobject
      Object that contains information about the breakdown of the transaction. Contains parameters required for Level 2, Level 3, and CEDP transactions.
      • convenienceFeeobject
        Object that contains information about the convenience fee for the transaction.+1 more fields at deeper levels — see the full spec
      • dutyAmountintegerint64
        Amount of duties or fees that apply to the order. The value is in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
      • freightAmountintegerint64
        Amount for shipping in the currency's lowest denomination, for example, cents. Required for Level 3 and CEDP transactions.
      • itemsobject[]
        Array of objects that contain information about each item that the customer purchased. Contains parameters required for Level 3 and CEDP transactions.+11 more fields at deeper levels — see the full spec
      • cashbackAmountintegerint64
        Amount of cashback for the transaction.
      • dualPricingobject
        Object that contains information about dual pricing.+6 more fields at deeper levels — see the full spec
      • healthcareExpensesobject[]
        Array of healthcareExpense objects that contain information about healthcare expenses.+2 more fields at deeper levels — see the full spec
      • subtotalintegerint64required
        Amount of the transaction before tax and fees. The value is in the currency’s lowest denomination, for example, cents. Required for Level 2, Level 3, and CEDP transactions.
      • surchargeobject
        Object that contains information about the surcharge.+3 more fields at deeper levels — see the full spec
      • tipobject
        Object that contains information about the tip.+4 more fields at deeper levels — see the full spec
      • taxesobject[]
        List of taxes.+3 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
    • dccOfferobject
      Object that contains information about the dynamic currency conversion (DCC) offer. For more information about DCC, go to Dynamic Currency Conversion.
      • acceptedboolean
        Indicates if the cardholder accepted DCC offer.
      • fxAmountintegerint64required
        Amount in the cardholder’s currency in the currency’s lowest denomination, for example, cents.
      • fxCurrencystringrequired
        Currency of the transaction in the card’s currency. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
      • fxCurrencyCodestring
        Three-digit currency code for the card. This code follows the ISO 4217 standard.3–3 chars
      • fxCurrencyExponentintegerint32
        Number of decimal places between the smallest currency unit and a whole currency unit. For example, for GBP, the smallest currency unit is 1p and it is equal to £0.01. If you use GBP, the value for fxCurrencyExponent is 2.
      • fxRatenumberdoublerequired
        Foreign exchange rate for the card's currency.
      • markupnumberdoublerequired
        Markup percentage rate that the DCC provider applies to the foreign exchange rate.
      • markupTextstring
        Supporting text for the markup rate.
      • offerReferencestring
        Unique identifier of the DCC offer.
      • providerstring
        Name of the DCC provider.
      • sourcestring
        Source that the DCC provider used to get the foreign exchange rates.
    • standingInstructionsobject
      Object that contains information about repeat payments. Include this object if the payment is part of a recurring billing schedule and you don't use our subscriptions feature.
      • processingModelstringrequired
        Indicates the type of payment schedule. 'unscheduled' – The payment is not part of a regular billing cycle. 'recurring' – The payment is part of a regular billing cycle with no end date. 'installment' – The payment is part of a regular billing cycle with an end date.unscheduledrecurringinstallment
      • referenceDataOfFirstTxnobject
        Object that contains information about the first payment.+2 more fields at deeper levels — see the full spec
      • sequencestringrequired
        Indicates if this payment is the first payment or if it is a subsequent payment.firstsubsequent
  • paymentIdstringrequired
    Unique identifier that our gateway assigned to the transaction.10–10 chars
  • processingTerminalIdstringrequired
    Unique identifier of the terminal that initiated the transaction.4–50 chars
  • refundsobject[]
    Array of refundSummary objects. Each object contains information about refunds linked to the transaction.
    • 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
  • supportedOperationsstring[]
    Array of operations that you can perform on the transaction. Our gateway can return any of the following values: capture Capture the payment. refund Refund the payment. fullyReverse Fully reverse the transaction. partiallyReverse Partially reverse the payment. incrementAuthorization Increase the amount of the authorization. adjustTip Adjust the tip post-payment. addSignature Add a signature to the payment. setAsReady Set the transaction’s status to `ready`. setAsPending Set the transaction’s status to `pending`.
  • transactionResultobjectrequired
    Object that contains information about the transaction response details.
    • approvalCodestring
      Authorization code that the processor assigned to the transaction.1–48 chars
    • authorizedAmountintegerint64
      Amount that the processor authorized for the transaction. This value is in the currency’s lowest denomination, for example, cents. Notes: For partial authorizations, this amount is lower than the amount in the request. If the value for authorizedAmount is negative, this indicates that the merchant sent funds to the customer.
    • cardSchemeReferenceIdstring
      Identifier that the card brand assigns to the payment instruction.1–64 chars
    • currencystring
      Currency of the transaction. The value for the currency follows the ISO 4217 standard.AEDAFNALLAMDANGAOAARSAUD+163 more
    • ebtTypestring
      Indicates the subtype of EBT in the transaction.cashPurchasecashPurchaseWithCashbackfoodStampPurchasefoodStampVoucherPurchasefoodStampReturnfoodStampVoucherReturncashBalanceInquiryfoodStampBalanceInquiry+1 more
    • healthcareIndicatorstring
      Indicates if we processed the payment as a healthcare expense. The value is one of the following: Y We processed the payment as a healthcare expense. N We processed the payment but it didn't contain any healthcare expenses. C We processed the payment but the card isn't linked to a Flexible Spending Account (FSA) or a Health Savings Account (HSA). R We processed the payment but the card doesn't support healthcare expenses.YNCR
    • 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. 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
      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 until the merchant captures the transaction. declined Unsuccessful transaction. The cardholder's issuing bank declined the transaction. complete Successful transaction. The funds have moved to the merchant's bank account. referral Unsuccessful transaction. The issuing bank identified an issue with the transaction. You should treat a referral status as a declined transaction. pickup Unsuccessful transaction. The issuing bank has reported that the card is lost or stolen. reversal Transaction canceled. The transaction was canceled, and we removed the transaction from the open batch. admin Transaction under review. We have flagged an issue with the transaction. expired Transaction expired. If a transaction stays in pending status for too long, it expires. accepted Transaction in progress. The transaction is in progress with the processor but we can't confirm the result yet.readypendingdeclinedcompletereferralpickupreversaladmin+2 more
    • typestring
      Transaction type.salerefundpreAuthorizationpreAuthorizationCompletion

Used in workflows

refund-a-card-paymentrun-a-pre-authorization

Search documentation

API reference169
Guides118
Knowledge38
legal1
Solutions32
Workflows74
↑↓highlight↵openView all search results

Menu

Theme

Sign out

Your saved plans remain in your organization. This browser’s private draft and account view will be cleared.

Talk to an engineer