List payins

get https://api.sandbox.rainforestpay.com/v1/payins

Query a list of payins given optional search criteria.

Query Params

merchant_id

string

The unique merchant identifier.

Prefix is "mid" in production and "sbx_mid" in sandbox.

merchant_name

string

Optional merchant name by which to filter.

method_type

string

Payment method type to filter by. Provide parameter multiple times to filter by multiple payment method types.

billing_contact_name

string

length between 1 and 50

Optional billing contact name by which to filter.

status

array of strings

One or more payin statuses to filter by. Provide parameter multiple times to filter by multiple payin status types.

AUTHORIZED CANCELED CREATED FAILED IN_REVIEW PRESENTING PROCESSING RETURNED SUCCEEDED

status

metadata

string

Filter by metadata stored on the entity by passing a map of key-value pairs to filter on. The key should be valid JSONPath to a corresponding metadata key.

For example, an entity created with the following metadata

"account": {
  "id": "acct_123"
}

could have the following metadata filter to find entities with the metadata account id:

?metadata[$.account.id]=acct_123

created_at.start

date-time

Created on or after in UTC RFC 3339 format.

created_at.end

date-time

Created on or before in UTC RFC 3339 format.

expected_deposit_date.start

date

Expected to be deposited on or after in UTC RFC 3339 format.

expected_deposit_date.end

date

Expected to be deposited on or before in UTC RFC 3339 format.

sort_by

string

Optional value by which to sort the result set. Default sort by is created_at.

sort_order

string

Order in which to return the sorted results; ascending or descending. Default sort order is descending.

limit

number

≤ 1000

Defaults to 1000

The maximum number of results to return.

offset

number

≥ 0

Defaults to 0

The offset of the first result to return; zero-based.

Headers

Rainforest-Api-Version

string

Defaults to 2024-10-16

Responses

Response body

object

status

string

data

object

last_key

string

Last ID in this result set.

This value can be be used as start_key in subsequent paginated requests to retrieve additional results whose IDs are greater than the last_key value.

total_results

integer

Total number of results available.

results

array of objects

List of payins.

results

object

payin_id

string

The unique payin identifier.

Prefix is "pyi" in production and "sbx_pyi" in sandbox.

payin_config_id

string

The unique payin config identifier.

Prefix is "cfg" in production and "sbx_cfg" in sandbox.

merchant_id

string

The unique merchant identifier.

Prefix is "mid" in production and "sbx_mid" in sandbox.

payment_method_id

string

The unique payment method identifier.

Prefix is "mtd" in production and "sbx_mtd" in sandbox.

payment_method_config_id

string

The unique payment method config identifier.

Prefix is "pmc" in production and "sbx_pmc" in sandbox.

device_registration_id

string

The unique device registration identifier.

Prefix is "dvc" in production and "sbx_dvc" in sandbox.

threeds_attempt_id

string | null

The unique threeds attempt identifier.

Prefix is "tds" in production and "sbx_tds" in sandbox.

idempotency_key

string

length between 1 and 255

A unique identifier provided by the platform. This key will be used to detect subsequent retries of the same request. Subsequent requests with the same key will return the result of the first request, regardless if the first request succeeded or failed. This identifier should be generated by the platform and can be max 255 characters.

billing_type

string

The merchant billing type. If omitted, the merchant will be assigned the platform's default billing type.

NET GROSS

amount

integer

The amount of the payin, in minor units.

For example, 1000 is 10.00 USD.

currency_code

string

length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

USD

is_partially_authorized

boolean

Boolean indicating if payin was authorized for a partial amount.

authorized_amount

integer

The amount of the payin that was authorized, in minor units.

For example, 1000 is 10.00 USD.

captured_amount

integer

The amount of the payin that was captured, in minor units.

For example, 1000 is 10.00 USD.

refundable_amount

integer

The amount of the payin that can still be refunded, in minor units.

For example, 1000 is 10.00 USD.

non_refundable_reason_code

string | null

Why the payin is nonrefundable. Provided when refundable_amount is 0.

VOIDED FAILED FULLY_REFUNDED HAS_CHARGEBACKS HAS_ACH_RETURN IN_ACH_RETURN_WINDOW IN_SETTLEMENT_WINDOW

status

string

The status of the payin.

AUTHORIZED CANCELED CREATED FAILED IN_REVIEW PRESENTING PROCESSING RETURNED SUCCEEDED

refusal_code

string

The code explaining the reason for the refusal if the payin or refund failed to process.

This value will be null if the payin or refund succeeded.

DECLINED DO_NOT_HONOR EXPIRED_CARD FRAUDULENT_CARD INCORRECT_PAYMENT_INFORMATION INSUFFICIENT_FUNDS INVALID_CARD_SECURITY_CODE INVALID_EXPIRATION_DATE INVALID_PIN LOST_CARD NO_CARD_NUMBER_ON_FILE_WITH_ISSUER NO_SUCH_CARD_ISSUER OVER_LIMIT PROCESSING_ERROR RESTRICTED_CARD_TYPE RETRY RETRY_WITH_THREEDS RISK_DECLINE STOLEN_CARD THREEDS_CHALLENGE_FAILED UNEXPECTED_PAYIN_TOKEN UNSUPPORTED_CARD_TYPE

refusal_desc

string

The description explaining the reason for the refusal if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user.

This value will be null if the payin or refund succeeded.

Declined Do not honor Expired card Fraudulent card Incorrect payment information Insufficient funds Invalid card security code Invalid expiration date Invalid PIN Lost card No card number on file with issuer No such card issuer Over limit Processing error Restricted card type Retry Retry with 3DS Risk decline Stolen card 3DS challenge failed Unexpected payin token Unsupported card type

detailed_refusal_code

string

The detailed refusal code that could be more descriptive than the refusal code. It may take up to 5 minutes for the detailed refusal code to populate after the payin or refund fails.

This value will be null if the payin or refund succeeded.

detailed_refusal_desc

string

The description explaining the detailed refusal reason if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user.

This value will be null if the payin or refund succeeded.

auth_code

string

The authorization code if the payin was approved.

avs_result_code

string

The address verification service result code.

cvc_result_code

string

The card verification code result code.

amount_splits

array of objects

length between 0 and 1

Represents the amount of the payin allocated to the platform.

Any remaining amount not specified by the amount splits was allocated to the merchant. If no amount splits are provided, the total amount was allocated to the merchant.

amount_splits

object

amount

integer

required

≥ 0

The amount split, in minor units.

For example, 1000 is 10.00 USD.

currency_code

string

required

length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

USD

type

string

required

The type of account the amount will be sent to. Set to PLATFORM to apply a platform fee.

PLATFORM

merchant_fees

object

The amount of the payin billed to the merchant.

method_type

string

The type of payment method.

CARD APPLE_PAY ACH PLAID_ACH

card

object

Card payment method details.

apple_pay

object

Apple Pay payment method details.

ach

object

ACH payment method details.

plaid_ach

object

ACH payment method details from Plaid.

billing_contact

object

Billing contact details.

device_data

object

Device data

method_metadata

object

Valid JSON key-value object specified by the platform to store additional information on the payment method. Keys are queryable in list endpoints. Do not use the metadata field to store sensitive or confidential data.

Metadata must be less than 8 KB in size.

Has additional fields

metadata

object

Valid JSON key-value object specified by the platform to store additional information. Keys are queryable in list endpoints. Do not use the metadata field to store sensitive or confidential data.

Metadata must be less than 8 KB in size.

Has additional fields

refunds

array of objects

refunds

object

refund_id

string

The unique refund identifier.

Prefix is "rfd" in production and "sbx_rfd" in sandbox.

payin_id

string

The unique payin identifier that was voided or refunded.

Prefix is "pyi" in production and "sbx_pyi" in sandbox.

merchant_id

string

The unique merchant identifier.

Prefix is "mid" in production and "sbx_mid" in sandbox.

amount

integer

The amount refunded, in minor units.

For example, 1000 is 10.00 USD.

currency_code

string

length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

USD

merchant_fees

object

The refund fee billed to the merchant.

reason

string

The reason a refund was issued.

status

string

The status of the refund.

CREATED PROCESSING SUCCEEDED FAILED CANCELED IN_REVIEW

refusal_code

string

The code explaining the reason for the refusal if the payin or refund failed to process.

This value will be null if the payin or refund succeeded.

refusal_desc

string

The description explaining the reason for the refusal if the payin or refund failed to process. This will be a human-readable value that may be presented to the end user.

This value will be null if the payin or refund succeeded.

auth_code

string

The authorization code if the refund was approved.

metadata

object

Valid JSON key-value object specified by the platform to store additional information. Keys are queryable in list endpoints. Do not use the metadata field to store sensitive or confidential data.

Metadata must be less than 8 KB in size.

Has additional fields

amount_splits

array of objects

length between 0 and 1

Represents the amount of the refund allocated to the platform.

Any remaining amount not specified by the amount splits was allocated to the merchant. If no amount splits are provided, the total amount was allocated to the merchant.

amount_splits

object

amount

integer

required

≥ 0

The amount split, in minor units.

For example, 1000 is 10.00 USD.

currency_code

string

required

length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

USD

type

string

required

The type of account the amount will be sent to. Set to PLATFORM to apply a platform fee.

PLATFORM

expected_deposit_date

date

Date the funds are expected to be available in a deposit.

created_at

date-time

Date and time void or refund was created at in UTC RFC 3339 format.

updated_at

date-time

Date and time refund was last updated at in UTC RFC 3339 format.

has_refunds

boolean

Boolean indicating that the payin has one or more refunds created.

chargebacks

array of objects

chargebacks

object

chargeback_id

string

The unique chargeback identifier.

Prefix is "chb" in production and "sbx_chb" in sandbox.

payin_id

string

The unique payin identifier.

Prefix is "pyi" in production and "sbx_pyi" in sandbox.

merchant_id

string

The unique merchant identifier.

Prefix is "mid" in production and "sbx_mid" in sandbox.

amount

integer

≥ 0

The amount of the chargeback, in minor units.

For example, 1000 is 10.00 USD.

currency_code

string

length between 3 and 3

Three-letter ISO currency code, in uppercase. Currently, only USD is supported.

USD

status

string

The status of the chargeback.

INQUIRY_ACTION_REQUIRED DISPUTE_ACTION_REQUIRED INQUIRY_RESPONDED CHARGEBACK_PROCESSING PRE_ARBITRATION_PROCESSING PROVISIONAL_WIN WON LOST ARBITRATION

metadata

object

Valid JSON key-value object specified by the platform to store additional information. This will contain metadata from the associated payin.

Has additional fields

merchant_fees

object

The dispute fee billed to the merchant.

method_type

string

The type of payment method.

CARD APPLE_PAY

card

object

Card payment method details.

apple_pay

object

Apple Pay payment method details.

reason_code

string

The code explaining the dispute reason for the chargeback.

PRODUCT_UNACCEPTABLE CREDIT_NOT_PROCESSED DUPLICATE FRAUDULENT GENERAL PRODUCT_NOT_RECEIVED SUBSCRIPTION_CANCELED UNRECOGNIZED

reason_desc

string

The description explaining the dispute reason for the chargeback. This will be a human-readable value that may be presented to the end user.

acquirer_ref

string

Acquirer Reference Number (ARN) is the unique identifier to trace the chargeback with the issuing bank.

due_date

date

Date chargeback times out and will be decisioned as a win or a loss depending on the current status.

chargeback_evidence

array of objects

chargeback_evidence

object

chargeback_evidence_id

string

The unique chargeback evidence identifier.

Prefix is "cbe" in production and "sbx_cbe" in sandbox.

chargeback_id

string

The unique chargeback identifier.

Prefix is "chb" in production and "sbx_chb" in sandbox.

is_required

boolean

Boolean indicating if evidence is required to dispute the chargeback.

type

string

The type of evidence.

3DS_VERIFICATION ADDITIONAL_AUTHORIZED_SIGNER ADDITIONAL_HOUSEHOLD_SIGNER AUTHORIZATION CANCELLATION_POLICY CVV2_CAPTURE DIGITAL_DOWNLOAD ORDER_FORM OTHER OTHER_PAYMENT_METHODS PRODUCT_OR_SERVICE_USAGE PROOF_OF_DELIVERY_TO_EMPLOYEE PROOF_OF_DELIVERY REBUTTAL RECEIPT RECURRING_BILLING_AGREEMENT RENTAL_AGREEMENT TRANSACTION_HISTORY

type_desc

string

The description explaining the type of evidence.

file_upload_mode

string

The mode for adding files to the evidence. If REQUIRED, the file_upload_ids must be set to respond to the chargeback.

ALLOWED NOT_ALLOWED REQUIRED

file_upload_ids

array of strings | null

List of file upload IDs for the evidence.

file_upload_ids

response_mode

string

The mode for adding a response to the evidence. If REQUIRED, the response must be set to respond to the chargeback.

ALLOWED NOT_ALLOWED REQUIRED

response

string | null

Plain text description to provide additional information for the chargeback evidence.

created_at

date-time

Date and time chargeback evidence was created at in UTC RFC 3339 format.

updated_at

date-time

Date and time chargeback evidence was last updated at in UTC RFC 3339 format.

validation_errors

array of objects

List of errors with the chargeback evidence to respond to the chargeback, if applicable.

validation_errors

object

field

string

The field in the request that had an error, if applicable.

code

string

The code describing the error.

message

string

The description of the error related to the field.

expected_deposit_date

date

Date the fee of the chargeback is expected to be deducted in a deposit. Funds pulled from the merchant or given to the merchant is dependent on the chargeback status and is not represented by the expected deposit date.

created_at

date-time

Date and time chargeback was created at in UTC RFC 3339 format.

updated_at

date-time

Date and time chargeback was last updated at in UTC RFC 3339 format.

has_chargebacks

boolean

Boolean indicating that the payin has one or more chargebacks created.

ach_return

object

The ACH return details.

has_ach_return

boolean

Boolean indicating that the payin has an ACH return.

payin_config

object

Payin config details.

threeds_attempt

object | null

3DS attempt details.

expected_deposit_date

date

Date the funds are expected to be available in a deposit.

created_at

date-time

Date and time payin was created at in UTC RFC 3339 format.

updated_at

date-time

Date and time payin was last updated at in UTC RFC 3339 format.

errors

array of objects

List of errors, if applicable.

errors

object

field

string

The field in the request that had an error, if applicable.

code

string

The code describing the error.

message

string

The description of the error related to the field.

200OK

400Bad request, check for validation errors.

401Authorization missing or invalid.

403Authorization insufficient for requested action.

5XXUnexpected error.