Skip to main content

Process Refund

POST 
/v1/settlements/:settlementId/refunds

Click on Send API Request after entering the required data, to see how to process a Refund request.

  • A regular Refund.

  • A Refund that is split into multiple merchant accounts. This is applicable for those merchants whose accounts are configured to do so.

Request​

Path Parameters

    settlementId stringrequired

    This is the ID returned in the response to the Process Payment request.

Header Parameters

    Content-Type string

    Possible values: [application/json]

    Simulator string

    Possible values: [EXTERNAL, INTERNAL]

    Default value: EXTERNAL

Body

    merchantRefNum stringrequired

    Possible values: <= 255 characters

    This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

    amount number

    Possible values: <= 99999999999

    This is the amount of the request, in minor units. For example, to process US $10.99, this value should be 1099.

    dupCheck boolean

    Default value: true

    This validates that this request is not a duplicate. A request is considered a duplicate if the merchantRefNum has already been used in a previous request within the past 90 days.

    Note: This value defaults to true.

    splitpay

    object[]

  • Array [

    • linkedAccount stringrequired

    This is the ID of the linked account. This account must already be linked to the merchant account.

    amount number

    This is the amount to transfer to the linked account in minor currency units. The total amount to all linked accounts cannot exceed the transaction total.

    percent number

    This is the percentage of the total transaction amount to transfer to that account. The total percentage to all linked accounts cannot exceed 100%.

  • ]

Responses​

Created

Response Headers

  • Content-Type

    string

Schema

    id uuid

    Possible values: <= 36 characters

    This is the ID returned in the response. This ID can be used for future associated requests.

    childAccountNum string

    Possible values: <= 10 characters

    This is child merchant account number. It is returned only if the transaction was processed via a master account.

    txnTime date-time

    This is the date and time the transaction was processed.

    status string

    Possible values: [RECEIVED, INITIATED, PENDING, FAILED, CANCELLED, EXPIRED, COMPLETED]

    This is the status of the transaction request. Possible values are:

    • RECEIVED – Our system has received the request and is waiting for the downstream processor's response.

    • INITIATED - The transaction was initiated with the downstream provider.

    • PENDING - The transaction is awaiting the payment service provider's response.

    • FAILED – The transaction failed due to an error or got declined.

    • CANCELLED – The transaction request is cancelled.

    • EXPIRED - The transaction request is expired.

    • COMPLETED – The transaction request is completed.

    error

    object

    Details of the error.

    code string

    The error code. Also shown in the X-Application-Status-Code response header.

    message string

    A description of the error.

    details string[]

    Details of any parameter value errors.

    fieldErrors

    object[]

    If applicable, this is a list of fields that have issues.

  • Array [

    • field string

    Identifies the JSON request field.

    error string

    The problem associated with field.

  • ]

    • riskReasonCode integer[]

    An array of integers is returned, displaying the detailed Risk reason codes if your transaction was declined. It is returned only if your account is configured accordingly.

    gatewayResponse

    object

    This is the read-only raw response returned by an acquirer. It is returned only if your account is configured accordingly.

    id string

    This is the response id returned by the processor

    processor string

    This is the processor code of the transaction at Paysafe side

    code string

    This is acquirer identification code, such as DJN, CRX, etc.

    responseCode string

    This is the raw response returned by the acquirer.

    avsCode string

    This is the raw AVS code returned by the acquirer.

    avsResponse string

    Possible values: [MATCH, MATCH_ADDRESS_ONLY, MATCH_ZIP_ONLY, NO_MATCH, NOT_PROCESSED, UNKNOWN]

    This is the AVS response returned from the card issuer.

    balanceResponse string

    This is the balance remaining on a gift card, if a gift card was used for the original transaction.

    mid string

    This is the acquirer MID that was sent to the clearing house.

    terminalId string

    This is the merchant's terminal ID.

    batchNumber string

    This is the batch number.

    seqNumber string

    This is the merchant's sequence number.

    effectiveDate string

    This is the date of the bank deposit associated with the transaction.

    financingType string

    This is the type of financing offered.

    plan string

    This is the plan number for this financing transaction.

    gracePeriod string

    This is the grace period, in months, associated with deferred payment transactions.

    term string

    This is the number of payments, in months, for equal payment transactions.

    responseId string

    This is the response ID assigned by Credorax.

    requestId string

    This is the request ID assigned by Paysafe.

    description string

    This is a description of the response.

    authCode string

    This is the authorization code.

    txnDateTime string

    This is the transaction date and time.

    referenceNbr string

    This is the Bank net transaction ID/Merch Tran Ref

    responseReasonCode string

    This is the raw response reason code returned by Credorax.

    cvvVerification string

    Possible values: [MATCH, NO_MATCH, NOT_PROCESSED, UNKNOWN]

    This is the response to the cvv submitted with the transaction request.

    cvv2Result string

    This is the raw cvv2 result code.

    status string

    This is the status of the transaction at the processor side.

    orderId string

    Unique NETELLER reference for the order.

    profile

    object

    This is customer's profile details.

    id string

    The customer's profile id in the system. If this is present rest all other fields are not required.

    status string

    The status of customer in the system, returned in the response.

    merchantCustomerId string

    Possible values: <= 10 characters

    This is the reference number for the customer created by the merchant and submitted as part of the request. It must be unique for each customer.

    Note: This value is mandatory when fundingTransaction is used.

    locale stringrequired

    Possible values: [en_US, fr_CA, en_GB, en_CA]

    This indicates the customer's locale preference.

    Note: Optional for GiroPay, Vippreferred-Direct-Registration. Not required for Paysafe Card Payouts.

    firstName stringrequired

    Possible values: <= 80 characters

    This is the customer’s first name.

    lastName stringrequired

    Possible values: <= 80 characters

    This is the customer’s last name.

    email stringrequired

    Possible values: <= 255 characters

    This is the customer's email address.

    phone string

    Possible values: <= 40 characters

    This is the customer's phone number.

    Note: Optional for GiroPay. Not required for Paysafe Card Payouts.

    dateOfBirth

    object

    This is the recipient's date of birth.

    day numberrequired

    Possible values: <= 31

    This is the day of birth.

    month numberrequired

    Possible values: <= 12

    This is the month of birth.

    year numberrequired

    Possible values: >= 1900

    This is the year of birth.

    mobile string

    Possible values: <= 40 characters

    Customer's mobile number.

    gender string

    Possible values: [M, F]

    This field indicates the Customer's gender.

    M - Male

    F - Female

    nationality string

    Possible values: <= 30 characters

    This field indicates the Customer's nationality.

    identityDocuments

    object[]

  • Array [

    • identityDocuments

    object[]

    required

    This is array of 2 JSON objects.

    • 1st object contains SSN

    • 2nd object contains Identity document details.

  • Array [

    • anyOf

    type stringrequired

    Possible values: [SOCIAL_SECURITY]

    Default value: SOCIAL_SECURITY

    Value will always be "SOCIAL_SECURITY" This is part of 1st JSON object.

    documentNumber stringrequired

    Possible values: <= 9 characters

    The customer’s social security number.

  • ]

  • ]

    • merchantRefNum stringrequired

    Possible values: <= 255 characters

    This is the merchant reference number created by the merchant and submitted as part of the request. It must be unique for each request.

    amount number

    Possible values: <= 99999999999

    This is the amount of the request, in minor units. For example, to process US $10.99, this value should be 1099.

    dupCheck boolean

    Default value: true

    This validates that this request is not a duplicate. A request is considered a duplicate if the merchantRefNum has already been used in a previous request within the past 90 days.

    Note: This value defaults to true.

    splitpay

    object[]

  • Array [

    • linkedAccount stringrequired

    This is the ID of the linked account. This account must already be linked to the merchant account.

    amount number

    This is the amount to transfer to the linked account in minor currency units. The total amount to all linked accounts cannot exceed the transaction total.

    percent number

    This is the percentage of the total transaction amount to transfer to that account. The total percentage to all linked accounts cannot exceed 100%.

  • ]

Loading...