API Structures

API structures are JSON objects used in the API calls to pass structured data in and out.

Account Currency Status Structure

The account currency status structure contains information about an account’s ability to process incoming and outgoing payments for a particular currency.

Fields

Field Type Description
currency String (255 chars) The ISO 4217 currency code.
incoming_payments_status String (255 chars) Ability to process incoming payments for this currency.

Possible values: ok and paused.
outgoing_payments_status String (255 chars) Ability to process outgoing payments for this currency.

Possible values: ok and paused.
account_review_status String (255 chars) Review status of an account for this currency.

Possible values: not_requested, pending, and review_ok.

Example

{
    "currency": "USD",
    "incoming_payments_status": "ok",
    "outgoing_payments_status": "ok",
    "account_review_status": "pending"
}

Address Structure

The address structure contains information about a street address.

Fields

Field Required Type Description
country Yes String (2 chars) The 2-letter ISO-3166-1 country code.
postal_code No String (14 chars) The the postcode/zip for the address.

US postal codes must be valid, 5 digit strings.
CA postal codes must be six digits. The format is `A1A 1A1`, where A is a letter and 1 is a digit, with a space separating the third and fourth characters.
UK postal codes must match the following regex: "^([G][I][R] ?0[A]{2})|((([A-Z][0-9]{1,2})|(([A-Z][A-HJ-Y][0-9]{1,2})|(([A-Z][0-9][A-Z])|([A-Z][A-HJ-Y][0-9]?[A-Z])))) ?[0-9][A-Z]{2})$".
This parameter is only optional when the app has the correct permissions.
address1 No String (60 chars) The first line of the street address.
address2 No String (60 chars) The second line of the street address.
city No String (30 chars) The city.
region No String (30 chars) Must be the 2-letter US state code for US addresses. Represents subdivisions (e.g. provinces or states) for other countries. 2-letter province codes are supported for Canada. 3-letter region codes are supported for Great Britain / UK (UK is not an accepted value here).

Note that the following values are not accepted for the controller or entity address: PR, VI, AA, AE, and AP.

Example

{
    "address1": "1525 Central Ave.",
    "address2": "",
    "city": "San Jose",
    "region": "CA",
    "postal_code": "95128",
    "country": "US"
}

Admin Context Structure

Describes the context of an account administrator.

Fields

Field Required Type Description
reason Yes String (255 chars) The reason the person is an administrator (role).

Possible values: other_organizer and other.
explanation Yes String (255 chars) An explanation of why the person is an administrator.

Example

{
    "reason": "other_organizer",
    "explanation": "This is the primary recipient's caretaker."
}

Balances Structure

The balances structure contains information on the account balances and automated withdrawals. Accounts can have multiple balances (one for each currency they support).

Fields

Field Type Description
currency String (3 chars) The ISO 4217 currency code.
balance Decimal (64 bits) The available balance for this account (specific to the currency specified).
incoming_pending_amount Decimal (64 bits) The amount of money that being sent to the account that is still pending.
outgoing_pending_amount Decimal (64 bits) The amount of money being settled to the merchant (either via check or ACH) that is still pending.
reserved_amount Decimal (64 bits) The amount of money held in reserves.
disputed_amount Decimal (64 bits) The amount of money disputed either via chargeback or through WePay.
withdrawal_type String (6 chars) How the money will be settled to the merchant.

Possible values: check and ach.
withdrawal_period String (6 chars) How often money will be settled to the merchant.

Possible values: daily, weekly, and monthly.
withdrawal_next_time Integer (64 bits) The Unix timestamp (UTC) for the next scheduled settlement.
withdrawal_bank_name String (6 chars) The masked name of the entity funds will be settled to. If a check is being sent, this will be the name of the entity the check was mailed to (the "pay to the order of" field).

Example of a USD Balance

{
    "currency": "USD",
    "balance": 390.5,
    "incoming_pending_amount": 635.3,
    "outgoing_pending_amount": 210.0,
    "reserved_amount": 0,
    "disputed_amount": 0,
    "withdrawal_period": "daily",
    "withdrawal_type": "ach",
    "withdrawal_next_time": 1370112217,
    "withdrawal_bank_name": "WellsFargo XXXXX3102"
}

Example of a CAD Balance

{
    "currency": "CAD",
    "balance": 40.5,
    "incoming_pending_amount": 20.3,
    "outgoing_pending_amount": 70.0,
    "reserved_amount": 0,
    "disputed_amount": 0,
    "withdrawal_period": "daily",
    "withdrawal_type": "ach",
    "withdrawal_next_time": 1370112217,
    "withdrawal_bank_name": "TD Canada XXXXX4156"
}

Bank Data Response Structure

The bank data structure contains information about the bank account for a withdrawal.

Fields

Field Type Description
bank_name String (255 chars) Nickname of the bank.
account_last_four String (255 chars) Last four digits of the bank account.
note String (255 chars) A short description of the reason for the withdrawal.

Example

{
    "bank_name": "TestBank XXXXXX3123",
    "account_last_four": "3123",
    "note": "Withdrawing money from the account"
}

Browser

Details about the device’s browser that was used in the checkout to optimize the authentication display. Note that defaults are currently in development, and this page will be updated once they are complete. It is highly recommended to fetch the user’s browser data and send it in this structure (even though there will be defaults) to ensure ideal user experience.

Browser information will not be present in the API response.

Arguments

Parameter Required Type Description
type No String The User-Agent header of the browser the payer used to check out.
challenge_iframe_size No Enum Dimensions of the challenge iframe (in width x height in pixels) displayed to the payer during 3D-Secure authentication. This field should be provided only if the challenge_mode value is being sent as iframe. The following enum values can be sent:
  • FULL_SCREEN
  • 250_X_400
  • 390_X_400
  • 500_X_600
  • 600_X_400
accept_headers No Enum The content of the Accept request-header field as sent from the payer's browser. The only accepted value is application/json.
color_depth No Integer (min: 1; max: 48) The bit depth (in bits per pixel) of the color palette for displaying images.
java_enabled No Boolean Indicates whether or not the payer's browser supports Java.
language No String The language supported for the payer's browser as defined in IETF BCP47, e.g. en_US.

Example

{
  "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
  "challenge_iframe_size": "FULL_SCREEN",
  "accept_headers": "application/json",
  "color_depth": 48,
  "java_enabled": true,
  "language": "en-US",
  "screen_height": 400,
  "screen_width": 250,
  "time_zone": 0
}

Capture Amounts

Fields

Field Type Description
amount Integer (64 bits) Use this field to send the monetary value to capture of the original checkout `amount`.
app_fee Integer (64 bits) Use this field to send the monetary value to capture of the original checkout `app_fee`.

Example

{
    "amount": 10,
    "app_fee": 1
}

Card Reader Structure

The card reader structure contains details on orders for card readers placed using WePay’s mPOS fulfillment service. It is only relevant to platforms using WePay’s mPOS service.

Fields

Field Type Description
model String (255 chars) Model of card reader (valid options are defined as part of your integration with mPOS.)

Example

{
    "model": "aaa"
}

Chargeback Response Structure

A chargeback occurs when a customer questions your charge with their bank or credit card company. When a customer disputes your charge, you are given the opportunity to respond to the dispute with evidence that shows the charge is legitimate.

The chargeback object specifies whether there was a chargeback and the amount charged back.

Fields

Field Type Description
amount_charged_back Decimal (64 bits) If this checkout has been fully or partially charged back, this is the amount that has been charged back so far.
dispute_uri String (255 chars) The URI that payers can visit to open a dispute for this checkout. Do not store the returned URI on your side as it can change.

Example

{
    "amount_charged_back": 40,
    "dispute_uri": ""
}

Check Data Response Structure

The check data structure contains information about a check issued for a withdrawal.

Fields

Field Type Description
name String (255 chars) Name of the recipient.
city String (30 chars) The city.
region String (2 chars) Will contain the 2-letter US state code for US addresses.
postal_code String (10 chars) The postcode/zip for the address.
country String (2 chars) The 2-letter ISO-3166-1 country code.
note String (255 chars) A short description of the reason for the withdrawal.
cashed_time Integer (64 bits) The Unix time when the check was cashed.

Example

{
    "name": "Bill Clerico",
    "city": "Redwood City",
    "region": "CA",
    "postal_code": "94063",
    "country": "US",
    "note": "Withdrawing money from the account",
    "cashed_time": 1332280083
}

Credit Card Additional Data

Object that specifies additional credit card data.

Fields

Field Required Type Description
transaction_token No String (255 chars) Used for making a checkout call if the credit card was EMV enabled.
emv_receipt No EMV Receipt Structure Structure containing receipt information for EMV transactions. This parameter should not be added to requests. It will only be present in response structures. (only present in API response)
signature_url No String (255 chars) Signature image URL. (only present in API response)

Example

{
    "transaction_token": "1234567890ABCDEF",
    "emv_receipt": {
        "application_label": null,
        "application_identifier": "A000000025010801",
        "terminal_identification": "001",
        "transaction_type": "00",
        "transaction_certificate": "8960887ACFD507FF",
        "authorization_code": "123456",
        "merchant_id": "123456789",
        "merchant_name": "EMV Merchant"
    }
}

Credit Card Structure

The Credit Card Structure object specifies the credit card ID used for tokenization.

Fields

Field Required Type Description
id Yes Integer (64 bits) Credit card ID from /credit_card/create.
data No Credit Card additional data Structure for passing in additional credit card information.
auto_capture No Boolean If present and set to false, the credit card will not be automatically charged, it will only be authorized for the amount set in /checkout/create. The authorized amount will show up as a pending charge on the payer's card statement. The associated checkout will not progress past the state of authorized until a call to /checkout/capture is made. If 7 days pass without having called /checkout/capture, the associated checkout will transition to state cancelled.

Default: true

Example

{
    "id": 1234,
    "data": {
        "transaction_token": "1234567890ABCDEF"
    },
    "auto_capture": true
}

Document Response Structure

The Document Response structure show file metadata for documents that have been uploaded to WePay.

Fields

Field Required Type Description
file_id Yes Integer (64 bits) The unique ID of a document uploaded by your merchant which is used by WePay for identity verification purposes.
type Yes String The document type, as specified when uploaded. Possible values:
  • passport
  • drivers_license
  • other_government_issued_photo_id
  • current_lease_contract
  • current_utility_bill
  • benefits_card
  • birth_certificate
  • certificate_of_citizenship
  • certificate_of_naturalization
  • certified_copy_of_court_order
  • employment_authorization_card
  • permanent_resident_card
  • social_security_card
  • social_insurance_number_card
  • evidence_of_corporate_registration
  • evidence_of_nonprofit_registration
  • evidence_of_authority
  • current_bank_statement
  • current_local_tax_bill
  • mortgage_statement
  • electoral_register_entry
state Yes String The document's WePay review state. Possible values: verified, in_review, and rejected.
reject_reason Yes String The reason why the document was rejected during review (if applicable). This is guaranteed to be non-null if the document's state is "rejected", otherwise, it will be null. Possible values: illegible, corrupt_file, info_mismatch, doc_unsupported, and incomplete.
create_time Yes Integer (64 bits) The Unix timestamp (UTC) (in seconds) when the document was uploaded to WePay.

Example

{
    "file_id": 5678,
    "type": "social_security_card",
    "state": "rejected",
    "reject_reason": "illegible",
    "create_time": 1480700500000
}

Device Information

Provide the payer’s device details so that the authentication display will be optimized. Note that defaults are currently in development, and this page will be updated once they are complete. It is highly recommended to fetch the user’s browser data and send it in this structure (even though there will be defaults) to ensure ideal user experience.

Device information will not be present in the API response.

Arguments

Parameter Required Type Description
browser No Object Details about the device's browser that was used in the checkout to optimize the authentication display. Note that defaults are currently in development, and this page will be updated once they are complete. It is highly recommended to fetch the user's browser data and send it in this structure (even though there will be defaults) to ensure ideal user experience.
ip_address No String The IP address of the device used by the payer.

Example

{
  "browser": {
    "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
    "challenge_iframe_size": "FULL_SCREEN",
    "accept_headers": "application/json",
    "color_depth": 48,
    "java_enabled": true,
    "language": "en-US",
    "screen_height": 400,
    "screen_width": 250,
    "time_zone": 0
  },
  "ip_address": "12.37.161.213"
}

Dispute Resolution Structure

The Dispute Resolution structure gives you more details on a resolution, like time of resolution and type.

Fields

Field Required Type Description
time_resolved Yes Integer Timestamp dispute is resolved.
type Yes String Resolution type. Possible values:
  • "For Payee"
  • "For Payer"
  • "Closed by Admin"
  • "Unknown"

Example

{
    "time_resolved": 12328323,
    "type": "Unknown"
}

Dispute Payee Information Structure

The Dispute Payee Information Structure allows the merchant to provide supporting information and help WePay resolve the dispute.

Fields

Field Required Type Description
account_id Yes Integer ID of the payee account. Used to determine whether they can access the dispute.
shipping_details No Object Shipping details like shipping service provider and order tracking number.
shipping_provider No String Shipping provider.
tracking_number No String Tracking number.
service_date Yes Integer Timestamp when service was rendered.
reason_for_payment Yes Enum Reason for payment. Possible values are:
  • payment_reason_donation
  • payment_reason_service
  • payment_reason_shippable_item
  • payment_reason_unknown
dispute_details Yes String Details about the dispute.
supporting_doc1_base64 No String Document #1 supporting the payee in this dispute. Base64 encoded.
supporting_doc2_base64 No String Document #2 supporting the payee in this dispute. Base64 encoded.
supporting_doc3_base64 No String Document #3 supporting the payee in this dispute. Base64 encoded.
supporting_doc4_base64 No String Document #4 supporting the payee in this dispute. Base64 encoded.
supporting_doc5_base64 No String Document #5 supporting the payee in this dispute. Base64 encoded.

Tip

Examples of supporting documents are communications with the payer, pictures of a product, shipping slips, etc.

Example

{
  "account_id": 1111,
  "reason_for_payment": "payment_reason_service",
  "dispute_details": "This message describes the dispute.",
  "service_date": 12333444444,
  "supporting_doc1_base64": "ABCDEF0123456789"
}

Email Message Structure

Specifies a short message to send to the payee and payer when a checkout is successful.

Fields

Field Required Type Description
to_payee No String (65535 chars) A short message that will be included in the payment confirmation email to the payee.
to_payer No String (65535 chars) A short message that will be included in the payment confirmation email to the payer.

Example

{
    "to_payee": "test",
    "to_payer": "test"
}

EMV Receipt Structure

Structure containing receipt information for EMV transactions.

Fields

Field Type Description
application_label String (64 chars) The label of the EMV Application.
application_identifier String (64 chars) The application identifier (AID).
terminal_identification String (64 chars) The terminal's identification number.
transaction_type String (2 chars) The type of financial transaction.
transaction_certificate String (16 chars) Cryptogram returned by the card when it approves a transaction.
authorization_code String (6 chars) The transaction authorization code.
merchant_id String (64 chars) The merchant ID (mid) used for the transaction.
merchant_name String (256 chars) The merchant's name.

Example

{
    "application_label": "American Express",
    "application_identifier": "A000000025010801",
    "terminal_identification": "001",
    "transaction_type": "00",
    "transaction_certificate": "8960887ACFD507FF",
    "authorization_code": "123456",
    "merchant_id": "123456789",
    "merchant_name": "EMV Merchant"
}

Fee Response Structure

Contains information about the app_fee, processing fee paid to WePay, and fee_payer.

Fields

Field Type Description
app_fee Decimal (64 bits) The dollar amount that the application will receive in fees. App fees go into the API applications WePay account. Limited to 20% of the checkout amount.
processing_fee Decimal (64 bits) The dollar amount paid to WePay as a fee.
fee_payer String (255 chars)

Who will pay the fees (WePay's fees and any app fees).

Possible values: payer, payee, payer_from_app, payee_from_app.

Example

{
    "app_fee": 20,
    "processing_fee": 20,
    "fee_payer": "payer"
}

Fee Structure

Specifies the app_fee and fee_payer parameters for a checkout. Visit our Best Practices section to understand the best way to implement fees for your platform.

Fields

Field Required Type Description
app_fee No Decimal (64 bits) The dollar amount that the application will receive in fees. App fees go into the API applications WePay account. Limited to 20% of the checkout amount.

Default: 0
fee_payer No String (255 chars)

Who will pay the fees (WePay's fees and any app fees).

  • Set to payer (case-sensitive) to charge fees to the person paying (payer will pay amount + fees, and payee will receive amount).
  • Set to payee to charge fees to the person receiving money (payer will pay amount, and payee will receive amount - fees).
  • Set to payer_from_app so that payer will be charged app fee (if there is one) and API application will be charged WePay fee.
  • Set to payee_from_app so that payee will be charged the app fee (if there is one) and the API application will be charged the WePay fee. Note that for the xxx_from_app calls: if the application's account goes negative, WePay will recover funds from bank account.
  • For EMV transactions the value must be either payee or payee_from_app.
Default: payer

Example

{
    "app_fee": 20,
    "fee_payer": "payer"
}

Hosted Checkout Response Structure

Contains the checkout URL, redirect URL, mode, theme object, and shipping information.

Fields

Field Type Description
auto_capture Boolean If present and set to false, the payment will not be automatically charged (will only be authorized) and the associated checkout will not progress past the state of authorized until a call to /checkout/capture is made, or if 7 days pass without having called /checkout/capture, the associated checkout will transition to state cancelled.

Default: true
checkout_uri String (2083 chars) The URI for the checkout.
mode String (255 chars) What mode the checkout was displayed in.

Possible values: iframe and regular.
redirect_uri String (2083 chars) The URI the payer will be redirected to after payment (if available).
shipping_fee Decimal The amount to be charged for shipping the item.
require_shipping Boolean If set to true, then the payer was required to enter their shipping address when paying.
shipping_address Shipping Address Structure If require_shipping was set to true and the payment was made, this will be the shipping address that the payer entered. If this value is null then either require_shipping is false, or the payer has not yet completed checkout.
theme_object Theme Structure The theme structure contains information to provide custom look-and-feel for the flows and emails.

Example

{
    "auto_capture": true,
    "checkout_uri": "http://wepay.com/checkout/1346959482/90404e3d/api_checkout?iframe=1",
    "redirect_uri": "http://www.test.com",
    "shipping_fee": 2,
    "require_shipping": true,
    "shipping_address": null,
    "theme_object": {
        "theme_id": 183446800,
        "name": "test",
        "primary_color": "ffffff",
        "secondary_color": "000000",
        "background_color": "ffffff",
        "button_color": "000000"
    },
    "mode": "regular"
}

Hosted Checkout Structure

Use this to have payers enter payment information on a WePay hosted checkout URL. Send either hosted_checkout or payment_method parameter. Do not send both parameters at the same time. If neither parameter is specified, default behavior will be hosted_checkout.

Fields

Field Required Type Description
redirect_uri No String (2083 chars) The URI the payer will be redirected to after payment (if available). If you do not pass a redirect_uri, the user will see a payment confirmation page.

Note: WePay does not allow underscores in subdomains, and using an underscore will violate the matching domain requirement.
mode No String (255 chars) What mode the checkout will be displayed in. The option is regular; the iframe mode has been deprecated.

Default: regular
fallback_uri No String (255 chars) The URI used to redirect the payer if 3rd party cookies are not enabled for iframes. Read more about this feature in the fallback URI article.

Note: iFrames, along with this parameter, have been deprecated.
shipping_fee No Decimal The amount to be charged for shipping the item.
require_shipping No Boolean If set to true, then the payer will be required to enter their shipping address when paying.

Default: false
prefill_info No Payments Prefill Info Structure Information about payer to pre-fill certain fields in checkout flow.
funding_sources No Array What payment method to accept for this checkout. Must be sent as an array.

Options are:
  • ["credit_card", "payment_bank"] to accept both credit card and bank payments.
  • ["credit_card"] to accept only credit card payments.
  • ["payment_bank"] to accept only payment bank payments.
For example, if only "credit_card" is selected, customers will see option to pay by credit card when they go to the WePay hosted checkout URL. They will not be able to pay using their bank account.

If the funding_sources parameter is not specified, both credit card and bank account payments will be accepted in the checkout flow.
theme_object No Theme Structure The theme structure contains information to provide custom look-and-feel for the flows and emails.
auto_capture No Boolean If present and set to false, the payment will not be automatically charged (will only be authorized) and the associated checkout will not progress past the state of authorized until a call to /checkout/capture is made, or if 7 days pass without having called /checkout/capture, the associated checkout will transition to state cancelled.

Default: true

Example

{
    "redirect_uri": "http://www.test.com",
    "fallback_uri": "http://www.test.com",
    "shipping_fee": 2,
    "mode": "regular",
    "require_shipping": true,
    "prefill_info": {
        "name": "Test Name",
        "email": "test@test.com",
        "address": {
            "address1": "1234 Test St.",
            "address2": "Ste. 100",
            "city": "Some City",
            "region": "CA",
            "postal_code": "94060",
            "country": "US"
        }
    },
    "theme_object": {
        "name": "test",
        "primary_color": "ffffff",
        "background_color": "ffffff",
        "button_color": "000000",
        "secondary_color": "000000"
    },
    "funding_sources": [
        "credit_card"
    ]
}

In-line Credit Card Structure

In-line credit card details.

Fields

Parameter Required Type Description
cc_number Yes String (255 chars) The number on the credit card.
expiration_month Yes Integer (32 bits) The expiration month on the credit card.
expiration_year Yes Integer (32 bits) The expiration year on the credit card.
user_name No String (255 chars) The full name of the user that the card belongs to. If no user name is given, WePay will auto-generate a username.
email No String (255 chars) Valid email address of the user the card belongs to. If the e-mail belongs to the merchant, your application's user account, or is invalid, the transaction may be canceled for risk reasons. If no email is given, WePay will send to an auto-generated address.
address Yes Address Structure The billing address on the card (a valid JSON object, not a JSON serialized string). US is assumed if country is not provided. Postal code will default to 99999 if not provided.
cvv No String The CVV (also known as a card security code, CVV2, or CVC) on the card.
This parameter is only optional when the app has the correct permissions.
reference_id No String (255 chars) The unique reference ID of the credit_card.
auto_capture No Boolean If present and set to false, the credit card will not be automatically charged (will only be authorized) and the associated checkout will not progress past the state of authorized until a call to /checkout/capture is made, or if 7 days pass without having called /checkout/capture, the associated checkout will transition to state cancelled.

Default: true
auto_update

 No Boolean Automatically update credit cards that have been stored with WePay. If a card is expired, or has been replaced (e.g., due to theft), it will be automatically updated based on information provided by card networks. To receive these updates, be sure to set a callback_uri.
callback_uri No (unless using auto_update) String (2083 chars) The URI that will receive IPNs for this credit card. You will receive an IPN whenever the card information is updated.

Note: Your platform may test using ports in staging but ports are not allowed in production.
virtual_terminal

 No Enum This is set if the merchant has manually entered the credit card number.

Possible values: web and mobile.
payment_request_flag No Boolean This is set if the credit card was obtained using the W3C Payment Request API.
recurring No Boolean Indicates if this is a recurring payment.
card_on_file No Boolean Indicates if the credit card is marked as on file.

Example

{
    "inline_credit_card": {
        "user_name": "Foo Bar",
        "email": "foob@wepay.com",
        "cc_number": "4111111111111111",
        "cvv": "873",
        "expiration_month": 10,
        "expiration_year": 2025,
        "address": {
            "address1": "631 Fake Blvd",
            "city": "Redwood city",
            "region": "CA",
            "country": "US",
            "postal_code": "94063"
        },
        "auto_capture": true,
        "auto_update": true
    }
}

International Phone Number Structure

The international phone number structure contains information to construct a valid E164 formatted phone number.

Fields

Field Required Type Description
country_code Yes String (255 chars) Numeric country code. Optional +, followed by 1-3 digits.
phone_number Yes String (255 chars) Country code and phone number.

Example

{
    "country_code": "+1",
    "phone_number": "5556667777"
}

Non Profit Information Structure

This structure contains information about a non profit entity

Fields

Field Type Description
legal_name String (255 chars) Legal name of the non-profit entity.
ein String (255 chars) Employer Identification Number of the non-profit entity.

Example

{
    "legal_name": "Org Name",
    "ein": "343644743"
}

Payer Response Structure

Contains information about the payer such as their name, email, and home address. This object is returned only if a payment has been made.

Fields

Field Type Description
name String (255 chars) The name of the person paying.
email String (255 chars) The email address of the person paying.
home_address Address Structure The home address of the person paying. Note that this value will return as null

Example

{
    "name": "John Doe",
    "email": "test@test.com",
    "home_address": "null"
}

Payment Method Structure

Send the payment method object to pay for a checkout using previously acquired payment information, such as a credit card (for tokenization) or preapproval.

Based on the type, only specify credit_card, inline_credit_card, payment_bank, or preapproval parameters. For example, if the payment method has type = credit_card, specify the credit_card parameter and do not specify the preapproval.

Fields

Field Required Type Description
type Yes String (255 chars) Payment Method type. Set to payment_bank, credit_card, inline_credit_card or preapproval to match the corresponding object type below. Only one corresponding object can be set.
inline_credit_card No In-line Credit Card Structure Object that specifies the in-line credit card.
credit_card No Credit Card Structure Object that specifies the credit card.
payment_bank No Payment Bank Structure Object that specifies the payment bank.
preapproval No Preapproval Structure Object that specifies the preapproval.

Example

{
    "type": "credit_card",
    "credit_card": {
        "id": 1334
    }
}

Payment Method Response Structure

Contains information about the payment method used.

Fields

Field Type Description
type String (255 chars) Payment Method type used in payment. Can be credit_card or payment_bank.
credit_card Credit Card Structure Object that specifies the credit card used in payment. Available if type is credit_card or inline_credit_card.
payment_bank Payment Bank Structure Object that specifies the payment bank used in payment. Available if type is payment_bank.
preapproval Integer (64 bits) The preapproval ID from the /preapproval/create call.

Example

{
    "type": "credit_card",
    "credit_card": {
        "id": 1334
    }
}

Payment Bank Structure

The payment bank structure object contains the unique ID for a payment bank.

Fields

Field Required Type Description
id Yes Integer (64 bits) The payment bank ID.

Example

{
    "id": 1234
}

Payment Bank Response Structure

Object that specifies the payment bank used in payment.

Fields

Field Type Description
id Integer (64 bits) Payment bank ID used in payment.
name String (255 chars) Name of bank from which payment was drawn.
type String (255 chars) Type of bank account from which payment was drawn. Can be Checking or Savings.

Example

{
    "id": 1234,
    "name": "WELLS FARGO BANK",
    "type": "Checking"
}

Payment Bank Payment Error Structure

This structure contains additional information related to the payment bank payment error that occurred on a checkout.

Fields

Field Type Description
code String (255 chars) The bank account code. See below for the mapping for the list of codes to their descriptions.
description String (255 chars) A description of what the code means. See below for the mapping of the list of codes to their descriptions.

Bank Account Codes

Code Description Recommended Action
R01 Insufficient funds in account Payer needs to resubmit payment with updated account information or a new account.
R02 Account is closed Payer needs to resubmit payment with updated account information or a new account.
R03 No account on file Payer needs to resubmit payment with updated account information or a new account.
R04 Invalid account number Payer needs to resubmit payment with updated account information or a new account.
R05 Unauthorized debit to consumer account Bank rejected payment request, no follow-up suggested.
R06 Returned at request of originating bank Payer needs to resubmit payment with updated account information or a new account.
R07 Authorization revoked by customer Payer needs to resubmit payment with updated account information or a new account.
R08 Payment stopped Payer needs to resubmit payment with updated account information or a new account.
R09 Insufficient collected funds in account being charged Payer needs to resubmit payment with updated account information or a new account.
R10 Customer advises not authorized or amount incorrect Bank rejected payment request, no follow-up suggested.
R11 Check truncation return Payer needs to resubmit payment with updated account information or a new account.
R12 Account sold to another financial institution Payer needs to resubmit payment with updated account information or a new account.
R13 Invalid ACH routing number Payer needs to resubmit payment with updated account information or a new account.
R14 Payee is deceased Bank rejected payment request, no follow-up suggested.
R15 Account holder is deceased Bank rejected payment request, no follow-up suggested.
R16 Account funds have been frozen Payer needs to resubmit payment with updated account information or a new account.
R17 Item returned because of invalid data Payer needs to resubmit payment with updated account information or a new account.
R18 Improper effective date Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R19 Amount error Payer needs to resubmit payment with updated account information or a new account.
R20 Account does not allow ACH transactions or limit has been exceeded Payer needs to resubmit payment with updated account information or a new account.
R21 Invalid company identification Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R22 Invalid individual ID Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R23 Credit entry refused by receiver Payer needs to resubmit payment with updated account information or a new account.
R24 Duplicate entry Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R25 Addenda record error Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R26 Mandatory field error Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R27 Trace number error Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R28 Routing/transit number check digit error Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R29 Corporate customer advised not authorized Bank rejected payment request, no follow-up suggested.
R30 RDFI not participant in check truncation program Payer needs to resubmit payment with updated account information or a new account.
R31 Permissible return entry Payer needs to resubmit payment with updated account information or a new account.
R32 Receiving bank non-settlement Payer needs to resubmit payment with updated account information or a new account.
R33 Return of item Payer needs to resubmit payment with updated account information or a new account.
R34 Limited participation originating bank Payer needs to resubmit payment with updated account information or a new account.
R35 Return of improper debit entry Payer needs to resubmit payment with updated account information or a new account.
R36 Return of improper credit entry Payer needs to resubmit payment with updated account information or a new account.
R37 Source document presented for payment Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R38 Stop payment on source document Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R39 Improper source document Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R40 Return of item by government agency Payer needs to resubmit payment with updated account information or a new account.
R41 Invalid Transaction Code Payer needs to resubmit payment with updated account information or a new account.
R42 Routing/transit number check digit error Payer needs to resubmit payment with updated account information or a new account.
R43 Invalid account number Payer needs to resubmit payment with updated account information or a new account.
R44 Invalid individual ID Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R45 Invalid individual or company name Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R46 Invalid payee indicator code Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R47 Duplicate enrollment Payer needs to resubmit payment with updated account information or a new account.
R50 State law affecting RCK acceptance Payer needs to resubmit payment with updated account information or a new account.
R51 Item is ineligible, notice not provided, signature not genuine, or original item altered for adjustment entry Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R52 Stop payment on item Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R53 Item and ACH entry presented for payment Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R61 Misrouted return - RDFI has placed incorrect routing/transit # in RDFI id field Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R67 Duplicate return Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R68 Untimely return - the return was not sent within the established timeframe Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R69 Field errors Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R70 Permissible return entry not accepted Payer needs to resubmit payment with updated account information or a new account.
R71 Misrouted dishonored return - incorrect routing/transit # in RDFI id field Payer needs to resubmit payment with updated account information or a new account.
R72 Untimely return - dishonored return was not sent within the established timeframe Payer needs to resubmit payment with updated account information or a new account.
R73 Timely original return - RDFI certifies the original return entry was sent within established timeframe for original returns Payer needs to resubmit payment with updated account information or a new account.
R74 Corrected return - RDFI is correcting a previous return entry that was dishonored because it contained incomplete or incorrect information Payer needs to resubmit payment with updated account information or a new account.
R75 Original return not a duplicate Payer needs to resubmit payment with updated account information or a new account.
R76 No errors found Payer needs to resubmit payment with updated account information or a new account.
R80 Cross-border payment coding error Payer needs to resubmit payment with updated account information or a new account.
R81 Non-participant in cross-border program Payer needs to resubmit payment with updated account information or a new account.
R82 Invalid foreign RDFI identification Payer needs to resubmit payment with updated account information or a new account.
R83 Foreign RDFI unable to settle Payer needs to resubmit payment with updated account information or a new account.
R84 Cross-border entry not processed by originating gateway operator Payer needs to resubmit payment with updated account information or a new account.
R94 Administrative return item was processed and resubmitted as a photocopy Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R95 Administrative return item was processed and resubmitted as a MICR-Split Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R97 Administrative return item was processed and resubmitted with corrected dollar amount Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R98 Indicates a return PAC (pre-authorized check); RDFI provides a text reason and indicated a new account number on the PAC itself Bank system error. Customer needs to use a different bank account, preferably at a different bank.
R99 Indicates a return PAC (pre-authorized check); RDFI provides a text reason on the PAC itself for which there is no equivalent return reason code Bank system error. Customer needs to use a different bank account, preferably at a different bank.

Example

{
    "code": "R23",
    "description": "Credit entry refused by receiver"
}

Payment Error Structure

This structure contains additional information about a payment error that occurred on a checkout. At present, only Pay With Bank (ACH) transactions may have additional information.

Fields

Field Type Description
type String (255 chars) The error type. This is set to payment_bank and matches the corresponding object type below.
payment_bank Payment Bank Payment Error Structure Information regarding the error regarding the payment using a bank account.

Example

{
    "type": "payment_bank",
    "payment_bank": {
        "code": "R23",
        "description": "Credit entry refused by receiver"
    }
}

Payments Prefill Info Structure

Specifies prefill information for checkout, preapprovals, and subscription flows.

Fields

Field Required Type Description
name No String (255 chars) The name of the person.
email No String (255 chars) The email address of the person.
phone_number No String (15 chars) The phone number of the person.
address No Address Structure The street address.

Example

{
    "name": "Bill Clerico",
    "phone_number": "555-555-5555"
}

Preapproval Structure

Object that specifies unique ID of the preapproval associated with the checkout.

Fields

Field Required Type Description
id Yes Integer (64 bits) Preapproval ID from /preapproval/create.

Example

{
    "id": 1234
}

Refund Response Structure

The refund object contains information about the amount refunded and reason for the refund.

Fields

Field Type Description
amount_refunded Decimal (64 bits) If this checkout has been fully or partially refunded, this has the amount that has already been refunded.
refund_reason String (255 chars) If the payment was refunded the reason why.

Example

{
    "amount_refunded": 20,
    "refund_reason": "test"
}

Shipping Address Structure

The shipping address structure contains information about a shipping address.

Fields

Field Type Description
name String (255 chars) The name of the person.
address1 String (60 chars) The first line of the street address.
address2 String (60 chars) The second line of the street address.
city String (30 chars) The city.
region String (30 chars) Must be the 2-letter US state code for US addresses. Represents subdivisions (e.g. provinces or states) for other countries. 2-letter province codes are supported for Canada. 3-letter region codes are supported for Great Britain.
postal_code String (14 chars) The the postcode/zip for the address.
country String (2 chars) The 2-letter ISO-3166-1 country code.

Example

{
    "name": "James Goodfellow",
    "address1": "1525 Central Ave",
    "address2": "",
    "city": "San Jose",
    "region": "CA",
    "postal_code": "95128",
    "country": "US"
}

Shipping Contact Structure

The shipping contact structure contains information about the recipient of an mPOS card reader. It is only relevant to platforms using WePay’s mPOS service.

Fields

Field Type Description
name String (255 chars) The name of the contact for this order.
company String (255 chars) The name of the company for this order (optional).
phone String (255 chars) The phone number of the contact for this order.
email String (255 chars) The email address of the contact for this order

Example

{
    "name": "James Goodfellow",
    "company": "Goodfellow Systems, Inc",
    "phone": "6505551212",
    "email": "joe@goodfellow.com"
}

Significant Beneficiaries Structure

Provide an array of information for each beneficiary. While the API references significant beneficiaries, this information must be collected for all beneficiaries of these funds.

Fields

Field Required Type Description
non_domestic_locations Yes* Array An array containing the ISO codes of the country/countries which beneficiaries are based in. This is only applicable if their country is different from the country the organization is based in.

Note: While this parameter is not required by the API, it is required for crowdfunding platforms and their merchants.

Example

{
    "non_domestic_locations": [
        "CA"
    ]
}

Strong Customer Authentication

Required for GBP checkouts and credit cards with a UK address and either Visa or MasterCard brand. Provide information allowing payers to authenticate the transaction or auth with their card issuer. Find more information on strong customer authentication here.

Arguments

Parameter Required Type Description
redirect_uri Yes String (2083 chars) The URL to which a payer is to be redirected upon completion of authentication process.
challenge_mode Yes Enum Indicate if the authentication challenge will be in iframe or page mode by using either the iframe or the page enumeration values.
device_information No Object Provide the payer's device details so that the authentication display will be optimized. Note that defaults are currently in development, and this page will be updated once they are complete. It is highly recommended to fetch the user's browser data and send it in this structure (even though there will be defaults) to ensure ideal user experience.

Example

{
   "redirect_uri": "https://www.example.com",
   "challenge_mode": "iframe",
   "device_information": {
     "browser": {
       "type": "MOZILLA/4.0 (COMPATIBLE; MSIE 5.0; WINDOWS 95)",
       "challenge_iframe_size": "FULL_SCREEN",
       "accept_headers": "application/json",
       "color_depth": 48,
       "java_enabled": true,
       "language": "en-US",
       "screen_height": 400,
       "screen_width": 250,
       "time_zone": 0
     },
     "ip_address": "12.37.161.213"
   }
}

Response

Response Type Description
redirect_uri String (2083 chars) The URL to which a payer is to be redirected upon completion of authentication process.
challenge_uri String The URI hosting the challenge page or iFrame that you must present to the payer for authentication.

Example

{
    "redirect_uri": "https://www.example.com",
    "challenge_uri": "https://www.stage-iframe.wepay.com/payer_authentication?checkout_id=123"
}

Theme Request Structure

The theme structure contains information providing custom look-and-feel for flows and emails.

Fields

Field Required Type Description
name Yes String (64 chars) The name for the theme.
primary_color Yes String (6 chars) The hex triplet for the primary color on important elements such as headers.
secondary_color Yes String (6 chars) The hex triplet for the secondary color on elements such as info boxes, and the focus styles on text inputs.
background_color Yes String (6 chars) The hex triplet for the the background color for onsite and iframe pages.
button_color Yes String (6 chars) The hex triplet for the the color for primary action buttons.

Example

{
    "name": "API Theme for API App: My Sample Application",
    "primary_color": "FFFFFF",
    "secondary_color": "000000",
    "background_color": "004C64",
    "button_color": "0084A0"
}

Theme Response Structure

The theme structure contains information providing custom look-and-feel for flows and emails.

Fields

Field Type Description
theme_id Integer (64 bits) The unique theme ID (assigned by WePay).
name String (64 chars) The name for the theme.
primary_color String (6 chars) The hex triplet for the primary color on important elements such as headers.
secondary_color String (6 chars) The hex triplet for the secondary color on elements such as info boxes, and the focus styles on text inputs.
background_color String (6 chars) The hex triplet for the the background color for onsite and iframe pages.
button_color String (6 chars) The hex triplet for the the color for primary action buttons.

Example

{
    "theme_id": 12345,
    "name": "API Theme for API App: My Sample Application",
    "primary_color": "FFFFFF",
    "secondary_color": "000000",
    "background_color": "004C64",
    "button_color": "0084A0"
}

Tracking Information Structure

The tracking information structure contains details on mPOS card reader shipments. It is only relevant to partners using WePay’s mPOS fulfillment service.

Fields

Field Type Description
tracking_service String (255 bits) The name of the service used for deliveries.
tracking_code String (255 bits) The tracking code provided by the delivery service.
status String (255 chars) The status of the package. One of: shipped, delivered, or returned.

Example

{
    "tracking_service": "FedEx",
    "tracking_code": "1Z234567890",
    "status": "shipped"
}

Withdrawal Data Response Structure

The withdrawal data structure contains information about a withdrawal.

Fields

Field Type Description
create_time Integer (64 bits) The Unix time when the withdrawal was created.
capture_time Integer (64 bits) The Unix time when the withdrawal was captured and credited to the payee's bank account. Returns 0 if withdrawal is not yet captured.
redirect_uri String (2083 chars) The URI that the account owner will return to after completing the withdrawal.
callback_uri String (2083 chars) The URI that we will post notifications to each time the state on this withdrawal changes.
withdrawal_uri String (2083 chars) The URI that you will send the account owner to to complete the withdrawal. Do not store the returned URI on your side as it can change.

Example

{
    "create_time": 1332280083,
    "capture_time": 0,
    "redirect_uri": "http://www.example.com/withdrawal/51341",
    "callback_uri": "http://www.example.com/withdrawal/callback/51341",
    "withdrawal_uri": "https://stage.wepay.com/api/withdrawal/54321/s341bxd"
}