Payout

POST api.ravelin.com/v2/payout

This endpoint is used to request a recommendation when making a payout to a supplier.

To request a recommendation at this endpoint use the payout checkpoint. Ravelin will then return a recommendation of ALLOW, REVIEW or PREVENT.

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

payout object required

The payout describing the earnings that a merchant is intended to pay to the supplier on their platform.

Show definition

payoutId string required

A unique identifier for this payout.

status string required

The stage of payout. This is used in reporting.

Please provide one of the following:

CREATED: The payout is yet to be submitted for processing, and is yet to be decide whether or not to send the payment.
PENDING: The payout is submitted for processing, and is yet to receive status updates from the payment provider.
PROCESSING: The payout request is received and currently being processed.
CANCELLED: The payout has been cancelled by the sender.
FAILED: Something went wrong, and the payout can no longer be fulfilled.
COMPLETED: The payout has been completed and funds have been transferred successfully.
BLOCKED: The payout has been blocked. For example, there are concerns with the payout or a potential issue with the recipient’s account.

earnings object required

An object of the payout amount breakdown. Each field should be a positive integer in the currency's basic units, representing how much to payout.

Show definition

totalNetAmount integer required

The total amount of money that a merchant wants to pay to their suppliers after deducting all fees, taxes, and other deductions. It represents the final amount that the supplier will receive after all the deductions have been made.

currency string required

Currency of the payout amount, as an ISO 4217 currency code.

Pattern: ^[a-zA-Z]{3}$

totalGrossAmount integer important

The total amount of money that the merchant initially wants to pay to their suppliers, before any deductions have been made.

baseAmount integer optional

The sum of the fixed/defined earnings that forms the base income of the supplier. This excludes additional earnings such as purchases/goods/services/streams.

compensationAmount integer optional

The sum of any approved compensations made to the supplier.

bonusAmount integer optional

The sum of bonus campaigns or tips earned throughout the payout period stated.

withheldTaxAmount integer optional

The amount of income tax withheld from the supplier's payout.

onPlatformRevenue integer optional

The total revenue sourced from various revenue streams (e.g. trips, listeners, views) during the payout period stated.

feeAmount integer optional

The sum of commission fees and any deductions (except the withheld income tax) made from the total gross amount.

revenueSource object important

This object contains a breakdown of a supplier's revenue from sales represented as integers, with each value corresponding to a specific revenue source. It allows Ravelin to retrieve the distribution of revenue for a given supplier, enabling us to gain insight into the different revenue streams.

Show definition

ads integer optional

The revenue amount generated from advertising. This can include any ads-driven purchases/royalties/earnings on the platform.

referral integer optional

The revenue amount generated from referrals. This can include any purchases made through a referral link to the product/platform.

promo integer optional

The revenue amount generated from purchases/payments/consumptions associated with a promo/campaign/coupon.

subscriptions integer optional

The revenue amount generated from consumers who paid for the supplier’s product via a subscription plan. This source consists of recurring billings from subscribers.

purchase integer optional

The revenue amount generated by one-time payments done to the supplier. This can include any purchases made in the platform by ordering a new item, paying for a trip, one-time donations to the artist/supplier/content creator.

others integer optional

The revenue amount generated by any other revenue sources not covered by the above fields.

periodStart integer important

The start time of the date range of earnings that is covered by this payout.

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

periodEnd integer important

The end time of the date range of earnings that is covered by this payout.

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

creationTime integer important

The time that the payout object is created by the merchant. If this value is unknown, you can set it to 'now'.

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

payoutTime integer important

The time that the payout is submitted to the payment processor.

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

schedule string important

The schedule on which the payout was created.

One of the following:

MONTHLY: The payout was created as a result of a monthly process.
WEEKLY: The payout was created as a result of a weekly process.
DAILY: The payout was created as a result of a daily process.
ON_DEMAND: The payout was not created on a schedule, it was initiated on-demand.

initiatedBy string important

The actor who initiated the payout.

One of the following:

AGENT: A customer support agent initiated the payout.
SUPPLIER: The supplier initiated the payout.
AUTOMATED: The payout was initiated via an automated process.

notificationEmail string important

Payout updates to be delivered to this email address (this info can be valuable if the email registered to receive payout notifications is different to the supplier.email field).

supplier object required

The supplier that is set as the recipient of this payout.

Show definition

supplierId string required

The unique identifier of the supplier.

type string required

The role of the supplier in order fulfilment.

One of:

driver - A taxi driver, private hire driver, chauffeur or other type of person that drives people in a passenger motor vehicle.
courier - A courier, bike courier or delivery driver.
restaurant - A restaurant or cafe that sells prepared food. May also provide delivery.
shop - A shop which sells goods other than prepared food. May also provide delivery.
seller - An individual who sells goods or services and which is not covered by any of the other supplier types.
contentCreator - A supplier that is creating content, for example, music, podcasts or video. The type of content creator should be set in the category field.
promoter - A supplier that promotes music concerts, festivals, sporting events or other events or experiences, or a supplier that promotes products or services, for example an affiliate partner.
other - Any other type of supplier which is not covered by the other types.

groupId string important

The unique identifier of the supplier's parent organisation.

groupName string important

The name of the supplier's parent organisation.

registrationTime integer important

The time that the supplier registered. If this value is unknown, you can set it to 'now' - Ravelin will retain the earliest value you have sent for this supplier ID.

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

email string important

The email address of the supplier.

emailVerifiedTime integer optional

The time at which the supplier verified their email, usually by following a link back to your website from an email you sent to their address.

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

name string important

The full name of the supplier.

telephone string important

The telephone number of the supplier. Best in E.164 format with an international dialing code.

telephoneVerifiedTime integer optional

The time at which the supplier verified their telephone number, usually by confirming a code from an SMS you sent to the number.

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

telephoneCountry string optional

The country the telephone number directs to. Note that the country is not an adequate replacement for the international dialing code in the Dominican Republic or Puerto Rico where multiple dialing codes are used.

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

homeLocation object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

taxAddress object optional

Store tax address information at the time of payout to compare it to suppliers’ other addresses. Tax info maps to each payout object and is immutable. This could be different in any subsequent payouts.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

market string optional

The logical region in which this supplier exists.

Pattern: ^[0-9a-z-]*$

marketCountry string optional

The logical country for this supplier. Doesn't change when the supplier is briefly abroad.

marketCity string optional

The logical city in which this supplier exists.

Pattern: ^[0-9a-z-]*$

level string optional

The name of the current level of the supplier.

employmentType string optional

This describes how the supplier is employed by your organisation, e.g. "selfEmployed", or "partTime".

transportType string optional

The type of transport this supplier uses.

category string optional

The highest level category that applies to this supplier.

accountType string optional

The type of account a supplier has, whether it is an individual or a business account.

INDIVIDUAL - To be used when the supplier account is an individual account, for example an individual person selling goods or an individual person creating content under their own name.
BUSINESS - To be used when the supplier account is a business account, for example when there is a business or organisation or company associated to the supplier account, a shop selling goods, a restaurant selling food or business creating content.

accountPlatform string optional

The platform where the supplier account was created.

identityVerified boolean optional

This field would be used to indicate the status of the supplier's identity verification process, which is usually conducted to ensure compliance with anti-money laundering and other regulations.

tags object optional

The tags to set or unset. Use the tag ID followed by true or false, depending on whether you want to set or unset the tag.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

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-_]*$

paymentMethod object important

A primary payout method for funds to be transferred in by the merchant.

One of the following:

card: A credit or debit card.

Show definition

methodType string required

Vault card payment method indicator.

One of: card, creditcard, or debitcard.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

scheme string optional

The card network or scheme, such as visa or mastercard. Ravelin will identify the scheme on your behalf if you send the cardBin, which should be preferred.

instrumentId string important

A unique identifier for the physical card, shared between customers. Used to link cards in Connect. Must not be a hash of the PAN.

If you use multiple PSPs who each generate their own equivalent of an instrumentId, you should consider prefixing their values to indicate their origin to avoid collisions. Common examples include Stripe's fingerprint, or Braintree's unique_number_identifier).

pan string pci, optional

The full Primary Account Number of the card. Used by Ravelin to generate the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

cardBin string important

The first six or eight digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

cardLastFour string important

The last four digits of the card number/PAN. Please note this will be truncated to the last two digits when an eight digit BIN is provided.

issuer string optional

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard boolean optional

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued string optional

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

expiryMonth integer important

The expiry month of the card.

expiryYear integer important

The expiry year of the card.

eWallet string optional

deprecated

The e-Wallet to which the customer associated the card.

One of: applepay, googlepay, samsungpay, amazonpay, or visacheckout.

nameOnCard string important

The cardholder name.

billingAddress object important

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

corporateCard boolean optional

Whether this payment method is a corporate card.

virtualCard boolean optional

Whether this payment method is a virtual card.

successfulRegistration boolean optional

Whether the card was successfully registered with your gateway/PSP.

registrationTime integer important

The time that the card was saved to the customer's account. (Not the card start date.)

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

lastVerified integer optional

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

compromised boolean optional

Whether the card has been compromised.

compromisedReason string important

The reason why the card is considered compromised.

One of: cloned, databreach, found, lost, stolen, frozen, defrosted, or uncompromised.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

active boolean optional

deprecated

Whether this card is still saved to the customer's account.

banned boolean optional

deprecated

Whether this card has been banned.

nickName string optional

deprecated

The nickname the customer has given the payment method.

cardType string optional

deprecated

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

paymentMethodCipher: An encrypted payment method, containing the full card details encrypted via a Ravelin SDK.

Show definition

methodType string required

Client-side encrypted card payment method indicator.

Only: paymentMethodCipher.

cardCiphertext string required, pci

The card ciphertext produced by the Ravelin SDK card encryption.

This field constitutes cardholder data, and submission of this field therefore requires PCI DSS SAQ-A or SAQ-AEP certification. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

aesKeyCiphertext string required

The AES Key ciphertext produced by the Ravelin SDK card encryption.

algorithm string required

The algorithm used to generate the ciphertexts.

paymentMethodId string optional

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

ravelinSDKVersion string optional

The version of the Ravelin SDK that performed this encryption.

keyIndex integer optional

The index of the public RSA key used to encrypt the card.

keySignature string optional

An identifier for the public key used during encryption.

billingAddress object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

registrationTime integer optional

When the payment method was added to the customer's account. Note: this is not the card start date.

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

ravelinjsVersion string optional

deprecated

The version of the ravelinjs library that performed this encryption.

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

Show definition

methodType string required

Indicator of a cash payment, or cash-based payment method (e.g. paysafecard).

Only: cash.

scheme string optional

The name of the cash-based payment service used, if applicable.

bankaccount: Bank Accounts.

Show definition

methodType string required

Bank account indicator.

Only: bankaccount.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

transferType string required

The type of transfer: whether the customer is initiating the payment, or you are withdrawing funds from the customer's bank account based on an agreement to initiate payments on their behalf. Use "push" for a customer-initiated payment (e.g. a bank transfer) and "pull" for a merchant-initiated payment (e.g. Direct Debit).

One of: push, or pull.

scheme string important

The name of the payment scheme or instrument used for the transfer of funds.

iban string optional

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

countryIssued string optional

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

accountAddress object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

accountType string optional

The type of the account.

One of the following:

SAVINGS: A savings account, which is designed to help customers save money and earn interest.
CURRENT: A checking account, which is designed for frequent transactions and typically has low or no interest rates.

accountOwnerName string optional

The name of the account owner.

accountOwnerType string optional

The type of customer or entity that the account is associated with, whether it's an individual or a business.

One of the following:

PERSONAL: A bank account owned and used by an individual for personal transactions. Can include joint accounts.
BUSINESS: A bank account owned by a company or organisation for business transactions.

bankCode string optional

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

bankName string optional

Name of bank which account belongs to.

bic string optional

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

accountNumber string optional

The account number issued by the bank.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

registrationTime integer important

The time that the card was saved to the customer's account. (Not the card start date.)

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

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

paypal: PayPal payments.

Show definition

methodType string required

PayPal indicator.

Only: paypal.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

payerId string optional

PayPal payer ID.

email string important

Account email address.

billingAddress object optional

The address of the account holder. It is common to have fewer location details for this address, but provide what you have.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

registrationTime integer important

The time that the card was saved to the customer's account. (Not the card start date.)

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

lastVerified integer optional

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

nickName string optional

The nickname for the payment method that the customer gives, if applicable.

countryIssued string optional

The two-character ISO 3166-1 account country_code sent by PayPal.

verifiedAccount boolean optional

The customer’s PayPal account status. Indicates whether the account is verified or not.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

banned boolean optional

deprecated

If the payment method has been banned

active boolean optional

deprecated

Whether the payment method is active for use by this account

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

Show definition

methodType string required

Credit payment indicator.

Only: credit.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

scheme string optional

The name of the store credit scheme used as a payment method, if applicable.

registrationTime integer optional

When the payment method was added to the customer's account.

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

lastVerified integer optional

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

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

invoice: This payment method should be used whenever the merchant provides credit to the customer.

Show definition

methodType string required

Invoice payment indicator.

Only: invoice.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

scheme string important

The name of the invoice or 'buy now, pay later' scheme used, if applicable.

registrationTime integer optional

When the payment method was added to the customer's account.

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

lastVerified integer optional

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

accountOwnerName string optional

The nickname for the payment method that the customers gives, if applicable.

accountAddress object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

email string optional

The email address used by the customer to register an invoice or 'buy now, pay later' payment method.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

wallet: A digital wallet payment method.

Show definition

methodType string required

Vault card payment method indicator.

Only: wallet.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

scheme string required

The name of the digital wallet scheme or electronic payment service.

cardScheme string optional

The card network or scheme of the card used within a wallet payment method, such as visa or mastercard. Ravelin will identify the cardScheme on your behalf if you send the cardBin, which should be preferred.

instrumentId string important

A unique identifier for the physical card, shared between customers. Used to link cards in Connect. Must not be a hash of the PAN.

pan string pci, optional

The full Primary Account Number of the card. Used by Ravelin to generate the instrumentId for this card. If specified, you do not need to provide instrumentId, cardBin or cardLastFour.

Only PCI DSS SAQ-D certified merchants should submit the PAN to Ravelin. You must not send requests containing this field to api.ravelin.com, and must instead use pci.ravelin.com.

Please see our PCI DSS documentation for more information.

cardBin string important

The first six digits of the card number/PAN. The Bank Identification Number (BIN), recently more commonly known as the Issuer Identification Number (IIN).

Given the BIN, Ravelin will populate the issuer, country of issuance, and card type on your behalf.

cardLastFour string important

The last four digits of the card number/PAN.

cardType string optional

deprecated

The card network or scheme, such as visa or mastercard. Ravelin will identify the cardType on your behalf if you send the cardBin, which should be preferred.

issuer string optional

The card issuer, who the true cardholder will report fraud to. Ravelin will identify the issuer on your behalf if you send the cardBin, which should be preferred.

prepaidCard boolean optional

Whether this is a prepaid debit card. Ravelin will identify whether the card is prepaid on your behalf if you send the cardBin which should be preferred.

countryIssued string optional

The country that the card was issued in. Ravelin will identify the country of issuance on your behalf if you send the cardBin, which should be preferred.

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

expiryMonth integer important

The expiry month of the card.

expiryYear integer important

The expiry year of the card.

nameOnCard string important

The cardholder name.

billingAddress object important

The address of the registered cardholder, as used to pass AVS checks. It is common to have fewer location details for this address, but provide what you have.

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

successfulRegistration boolean optional

Whether the card was successfully registered with your gateway/PSP.

registrationTime integer important

The time that the card was saved to the customer's account. (Not the card start date.)

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

lastVerified integer optional

The time at which the payment method was last verified by the customer. An example mechanism would be a random amount charged to the customer's card that they can confirm the amount of.

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

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

active boolean optional

deprecated

Whether this card is still saved to the customer's account.

banned boolean optional

deprecated

Whether this card has been banned.

nickName string optional

deprecated

The nickname the customer has given the payment method.

fromTransaction: 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

methodType string required

Only: fromTransaction.

transactionId string important

The transaction ID to look up the payment method from.

gateway string important

The gateway that the transaction was processed through.

gatewayReference string important

The gateway ref provided by the gateway for the transaction.

paymentMethodId string optional

When present, will duplicate the payment method from the referenced transaction and save it under this paymentMethodId for use later. Used by Saving payment methods after checkout.

~~directdebit: Direct Debits.~~ - deprecated.

Show definition

methodType string required

Direct Debit indicator.

Only: directdebit.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

transferType string required

Bank transfer type

Only: directdebit.

scheme string required

The type of direct debit scheme.

One of: autogiro, bacs, becs, becsnz, betalingsservice, or sepa.

iban string optional

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

countryIssued string optional

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

accountAddress object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

accountOwnerName string optional

The name of the account owner.

bankCode string optional

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

bankName string optional

Name of bank which account belongs to.

bic string optional

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

accountNumber string optional

The account number issued by the bank.

mandateRef string optional

The unique reference issued for the direct debit mandate.

mandateURL string optional

A URL to access the direct debit mandate agreement.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

~~banktransfer: Bank Transfers.~~ - deprecated.

Show definition

methodType string required

Bank transfer indicator.

Only: banktransfer.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

transferType string required

Bank transfer type

One of: bancontact, eps, giropay, ideal, inghomepay, sofort, or sepa.

iban string optional

IBAN (International Bank Account Number) Following the ISO 13616:2007 standard.

countryIssued string optional

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

accountAddress object optional

Show definition

country string important

A ISO 3166-1 Alpha 3 or Alpha 2 country code.

postalCode string important

The postal or zip code. If provided without latitude or longitude, Ravelin will perform coarse geolocation in some countries.

latitude number important

The latitude of the location.

longitude number important

The longitude of the location.

addresseeName string optional

The name of the person that will accept delivery of goods to this address.

street1 string optional

The street address of the location.

street2 string optional

The street address of the location.

neighbourhood string optional

The neighbourhood of the location.

zone string optional

The zone of the location.

city string optional

The city/village/town

region string optional

The state/county of the location.

poBoxNumber string optional

The PO box number related to the location.

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

geohash string optional

deprecated

The geohash of the location.

accountOwnerName string optional

The name of the account owner.

bankCode string optional

Code assigned by central bank to identify bank that account is associated with. Multiple bank code formats are supported.

bankName string optional

Name of bank which account belongs to.

bic string optional

BIC - business identifier code for banks and other institutions. Following the ISO9362 standard.

accountNumber string optional

The account number issued by the bank.

nickName string optional

The nickname for the payment method that the customers gives, if applicable.

registrationTime integer important

The time that the card was saved to the customer's account. (Not the card start date.)

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

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

~~Others~~ - deprecated.

Show definition

methodType string required

Other method type indicator.

One of: voucher, bitcoin, transfer, paysafe, cheque, or edenred.

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

registrationTime integer optional

When the payment method was added to the customer's account.

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

lastVerified integer optional

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

custom object optional

Custom data that is relevant to your domain. This can be any json object. Please include any details that you think are relevant to fraud that our schema does not capture.

nickName string optional

deprecated

The nickname for the payment method that the customers gives, if applicable.

banned boolean optional

deprecated

If the payment method has been banned

active boolean optional

deprecated

Whether the payment method is active for use by this account

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

Show definition

paymentMethodId string required

A unique identifier for this payment method, specific to this customer. Two customers should not use the same paymentMethodId.

active boolean required

False to indicate the payment method has been deactivated.

Only: false.

paymentMethods array optional

deprecated

A primary payout method for funds to be transferred in by the merchant.

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

{
  "timestamp": 1512828988826,
  "payout": {
    "payoutId": "abc-123-ZYZ",
    "status": "CREATED",
    "earnings": {
      "currency": "GBP",
      "totalGrossAmount": 6000,
      "baseAmount": 1000,
      "compensationAmount": 200,
      "bonusAmount": 800,
      "withheldTaxAmount": 5000,
      "onPlatformRevenue": 9000,
      "totalNetAmount": 6000,
      "feeAmount": 6000
    },
    "revenueSource": {
      "ads": 1000,
      "referral": 2000,
      "promo": 3000,
      "subscriptions": 1500,
      "purchase": 2500,
      "others": 0
    },
    "periodStart": 1667260800000,
    "periodEnd": 1669852800000,
    "creationTime": 1512828988826,
    "payoutTime": 1512828988826,
    "schedule": "MONTHLY",
    "initiatedBy": "SUPPLIER",
    "notificationEmail": "jsmith123@example.com"
  },
  "supplier": {
    "supplierId": "abc-123-ZYZ",
    "groupId": "abc-123",
    "groupName": "Burger Chain",
    "registrationTime": 1512828988826,
    "email": "jsmith123@example.com",
    "emailVerifiedTime": 1512828988826,
    "name": "John Smith",
    "telephone": "+16045555555",
    "telephoneVerifiedTime": 1512828988826,
    "telephoneCountry": "GBR",
    "homeLocation": {
      "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"
    },
    "taxAddress": {
      "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"
    },
    "type": "driver",
    "level": "gold",
    "employmentType": "selfEmployed",
    "transportType": "car",
    "category": "private-hire",
    "accountType": "INDIVIDUAL",
    "accountPlatform": "anchor",
    "identityVerified": false,
    "tags": {
      "foo": true,
      "bar": false
    }
  },
  "paymentMethod": {
    "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"
  },
  "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"
    }
  ]
}

Feedback

Was this page helpful?