Refund

To request a recommendation at this endpoint use the Refund Request checkpoint.

Refund abuse recommendations need to be enabled on your account before they can be used. Please speak to your account manager about enabling refund abuse recommendations.

POST api.ravelin.com/v2/refund

The Refund API endpoint allows you to request a recommendation from Ravelin on whether you should refund a customer.

See our Refund Abuse Integration Guide for how to use the Refund API endpoint to prevent refund abuse.

Show all definitions
timestamp integer required

The time at which this data payload was valid. When sending events in realtime, this will usually be 'now'. This is used to merge data that arrives out-of-order.

A Unix timestamp preferably as an integer count of milliseconds since 1970-01-01T00:00 UTC (nanoseconds are also accepted).

customer object required

The customer requesting a refunds.

Show definition
refund object required

The refund describing the goods or services the customer wants to, or has attempted to return.

Show definition
order object required

The order describing the goods or services the customer wants to, or has attempted to buy.

Show definition
eventType string optional

An eventType should identify what event in your system triggered this API call.

Pattern: ^[a-zA-Z0-9][a-zA-Z0-9-_]*$
paymentMethods array important

One or more payment methods where the refund is being issued to.

One of the following:

Card - A credit or debit card.

Show definition

Payment Method Cipher - An encrypted payment method, containing the full card details encrypted via a Ravelin SDK.

Show definition

Cash - The customer is paying in cash, or a cash-based payment method.

Show definition

Bank Account - Bank Accounts.

Show definition

PayPal - PayPal payments.

Show definition

Credit - This payment method type should be used for any payments made using credit that a customer has with the merchant.

Show definition

Invoice - This payment method should be used whenever the merchant provides credit to the customer.

Show definition

Wallet - A digital wallet payment method.

Show definition

From Transaction - Refer to the payment method used by a named transaction. For usage examples, see Saving payment methods after checkout and Associating refunds with payment methods.

Show definition

Direct Debit - Direct Debits. - deprecated.

Show definition

Bank Transfer - Bank Transfers. - deprecated.

Show definition

Other - Other supported payment methods. - deprecated.

Show definition

Removal: Used for marking a saved payment method as removed from the account.

Show definition
transactions array important

One or more attempts for the payment method to be refunded for an order.

Show definition
device object optional

The device used by the customer to trigger this update.

Show definition
POST https://api.ravelin.com/v2/refund HTTP/1.1
Authorization: token ...
Content-Type: application/json

{
  "timestamp": 1512828988826,
  "customer": {
    "customerId": "abc-123-ZYZ",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "familyName": "Smith",
    "givenName": "John",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "DOM"
  },
  "refund": {
    "refundId": "abc-123-ZYZ",
    "status": "OPEN",
    "refundRequestTime": 1512828988826,
    "refundIssuedTime": 1512828988826,
    "amount": 10000,
    "currency": "GBP",
    "nonRefundableAmount": 10000,
    "refundIssuedTo": [
      "ORIGINAL_PAYMENT_METHOD",
      "GIFT_CARD"
    ],
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ]
  },
  "order": {
    "orderId": "abcde12345-ZXY",
    "creationTime": 1512828988826,
    "app": {
      "name": "Our App Lite",
      "platform": "web",
      "domain": "us.brand.com"
    },
    "status": {
      "stage": "pending",
      "actor": "merchant"
    },
    "price": 10000,
    "currency": "GBP",
    "country": "GBR",
    "market": "emea",
    "marketCity": "london",
    "category": "delivery",
    "to": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "from": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    },
    "items": [
      {
        "sku": "delivery",
        "quantity": 1,
        "name": "Delivery Fee",
        "price": 10000,
        "currency": "GBP",
        "category": "delivery",
        "executionTime": 1512828988826,
        "eventTicket": {
          "ticket": {
            "ticketId": "ticket_123",
            "ticketType": "Adult Single Day Pass",
            "validFromTime": 1480330580,
            "validUntilTime": 1480340580
          },
          "event": {
            "eventId": "event_123",
            "name": "The Fitzwilliam Museum.",
            "description": "Fitzwilliam Museum, Exhibition of Old Things",
            "startTime": 1480340580,
            "endTime": 1480340580,
            "category": "music",
            "venue": {
              "name": "Royal Albert Hall",
              "location": {
                "country": "GBR",
                "postalCode": "E1 1AA",
                "latitude": 51.503252,
                "longitude": -0.127899,
                "addresseeName": "John Smith",
                "street1": "123 fake st.",
                "street2": "floor 4, flat 48",
                "neighbourhood": "Hackney",
                "zone": "1",
                "city": "London",
                "region": "California",
                "poBoxNumber": "1234"
              }
            }
          },
          "guest": {
            "familyName": "Smith",
            "givenName": "John",
            "name": "John Smith"
          }
        }
      }
    ],
    "email": "jsmith@example.com",
    "telephone": "+441234558887",
    "telephoneCountry": "GBR",
    "sellerId": "abcde12345-ZXY",
    "executionTime": 1512828988826,
    "suppliers": [
      {
        "supplierId": "abc-123-ZYZ",
        "status": {
          "stage": "fulfilled",
          "timestamp": 1512828988826,
          "reason": "Could not find passenger"
        },
        "fee": 250,
        "debt": 1000,
        "tip": 200,
        "currency": "GBP",
        "type": "courier"
      }
    ]
  },
  "paymentMethods": [
    {
      "methodType": "card",
      "paymentMethodId": "pm-abc123",
      "scheme": "visa",
      "instrumentId": "fp_abc123",
      "cardBin": "535522",
      "cardLastFour": "0001",
      "expiryMonth": 7,
      "expiryYear": 2020,
      "eWallet": "applepay",
      "nameOnCard": "John Smith",
      "billingAddress": {
        "country": "GBR",
        "postalCode": "E1 1AA",
        "latitude": 51.503252,
        "longitude": -0.127899,
        "addresseeName": "John Smith",
        "street1": "123 fake st.",
        "street2": "floor 4, flat 48",
        "neighbourhood": "Hackney",
        "zone": "1",
        "city": "London",
        "region": "California",
        "poBoxNumber": "1234"
      },
      "corporateCard": true,
      "virtualCard": true,
      "successfulRegistration": true,
      "registrationTime": 1512828988826,
      "lastVerified": 1512828988826,
      "compromised": true,
      "compromisedReason": "stolen",
      "billingFamilyName": "Smith",
      "billingGivenName": "John"
    }
  ],
  "transactions": [
    {
      "transactionId": "123-abc-XYZ",
      "time": 1480340580291,
      "amount": 10000,
      "currency": "GBP",
      "type": "refund",
      "paymentMethodId": "pm-abc123",
      "gateway": "example-gateway",
      "gatewayReference": "123-abc-XYZ",
      "success": true,
      "mcc": "0742",
      "mid": "mid-1",
      "acquirerId": "adyen",
      "acquirerBin": "123456",
      "acquirerCountryCode": "GBR"
    }
  ],
  "device": {
    "deviceId": "65fc5ac0-2ba3-4a3b-aa5e-f5a77b845260",
    "ipAddress": "81.152.92.84",
    "language": "en-US",
    "userAgent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_4) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/69.0.3497.100 Safari/537.36",
    "model": "Pixel XL",
    "os": "android",
    "type": "phone",
    "manufacturer": "google",
    "location": {
      "country": "GBR",
      "postalCode": "E1 1AA",
      "latitude": 51.503252,
      "longitude": -0.127899,
      "addresseeName": "John Smith",
      "street1": "123 fake st.",
      "street2": "floor 4, flat 48",
      "neighbourhood": "Hackney",
      "zone": "1",
      "city": "London",
      "region": "California",
      "poBoxNumber": "1234"
    }
  }
}

Feedback

© Ravelin Technology Ltd. All rights reserved