Payment Method

This endpoint is used to inform Ravelin of payment methods being saved or used by a customer account.

The data that you use to populate the payment method varies between payment service providers (PSP) after tokenization. If your PSP is unable to provide you with a suitable instrument ID you should allow Ravelin to generate instrument IDs on your behalf by submitting either full PANs, or client-side encrypted cards. For more information, please refer to our PCI DSS documentation.

Ravelin does not accept submission of the CVV, PIN or magnetic stripe data to any of our API endpoints.

To request a recommendation at this endpoint use the Payment Method Registration checkpoint.

Field Status Definitions
Required Required fields must be sent. If the data is not sent Ravelin will return an error.
Important Important fields are crucial for performance where that data is relevant for your business.
Optional Optional fields are additional data points that can be shared with Ravelin.
These fields are unlikely to impact performance but may be visible in the Ravelin dashboard.

POST api.ravelin.com/v2/paymentmethod

Show all
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).

customerId string required

The unique identifier of the customer. If your system allows anonymous checkout then we recommend making this the customer's email address.

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-_]*$
tempCustomerId string optional
deprecated

Deprecated. Use customerId instead.

paymentMethod object optional

The payment method being registered by the customer.

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
device object optional

The device used by the customer to trigger this update.

Show definition
deviceId string optional

The ID of the device used by the customer to trigger this update.

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

{
  "timestamp": 1512828988826,
  "customerId": "abc-123-ZYZ",
  "tempCustomerId": "abc-123-XYZ",
  "paymentMethod": {
    "methodType": "card",
    "paymentMethodId": "pm-abc123",
    "scheme": "visa",
    "instrumentId": "fp_abc123",
    "paymentAccountReference": "50019P9LBXOLHN9G7QMU5VN520YSY",
    "cardBin": "535522",
    "cardLastFour": "0001",
    "expiryMonth": 7,
    "expiryYear": 2020,
    "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",
    "eWallet": "applepay"
  },
  "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"
    }
  }
}

Response

Show all
status integer

The HTTP response status code.

timestamp integer

A Unix timestamp indicating when we finished handling the request.

message string

If an error has occurred, a description of the error.

data object

Contains our recommendations and related details.

Show definition
{
  "status": 200,
  "timestamp": 1512828988826,
  "data": {
    "action": "ALLOW",
    "score": 12,
    "source": "RAVELIN",
    "customerId": "abc-123-ZYZ",
    "scoreId": "2bf39d-d1299-31",
    "transactionOptimisation": {
      "transactionId": "123-abc-XYZ",
      "action": "AUTHENTICATE",
      "exemption": "TRANSACTION_RISK_ANALYSIS",
      "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
      "actionSource": "CLIENT_RULE",
      "rules": {
        "triggered": [
          {
            "ruleId": 1,
            "ruleVersion": 1,
            "action": "AUTHENTICATE",
            "exemption": "TRANSACTION_RISK_ANALYSIS",
            "threeDSChallengePreference": "NO_CHALLENGE_REQUESTED",
            "triggered": true,
            "state": "active"
          }
        ]
      }
    },
    "warnings": [
      {
        "class": "customer-not-found",
        "help": "https://developer.ravelin.com/api/warnings/#customer-not-found",
        "msg": "Customer \"abc-123-ZYZ\" not found."
      }
    ]
  }
}

Feedback