WePay

Address Structure

The address structure contains information about a street address.

Fields:

Field Type Description
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.
state String (2 chars) The 2-letters US state code. Only for US addresses.
region String (30 chars) The region. Only for non-US addresses when available.
zip String (10 chars) The US zip or zip-plus code. Only for US addresses.
postcode String (14 chars) The postcode. Only for non-US addresses when available.
country String (2 chars) The 2-letters ISO-3166-1 country code.

Example:

US Address:

{
    "address1":"380 Portage Ave",
    "address2":"",
    "city":"Palo Alto",
    "state":"CA",
    "zip":"94306",
    "country":"US"
}
    

Non-US Address:

{
    "address1":"100 Main St",
    "address2":"",
    "region":"ON",
    "city":"Toronto",
    "postcode":"M4E 1Z5",
    "country":"CA"
}
    

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.
state String (2 chars) The 2-letters US state code. Only for US addresses.
region String (30 chars) The region. Only for non-US addresses when available.
zip String (10 chars) The US zip or zip-plus code. Only for US addresses.
postcode String (14 chars) The postcode. Only for non-US addresses when available.
country String (2 chars) The 2-letters ISO-3166-1 country code.

Example:

US Address:

{
	"name":"Bill Clerico",
	"address1":"380 Portage Ave",
	"address2":"",
	"city":"Palo Alto",
	"state":"CA",
	"zip":"94306",
	"country":"US"
}
	

Non-US Address:

{
	"name":"Bill Clerico",
	"address1":"100 Main St",
	"address2":"",
	"region":"ON",
	"city":"Toronto",
	"postcode":"M4E 1Z5",
	"country":"CA"
}
	

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 (and if you are using the iframe we will send a postMessage to the parent window indicating that the payment is complete).
mode No String (255 chars) What mode the checkout will be displayed in. The options are 'iframe' or 'regular'. Choose 'iframe' if this is an iframe checkout. Mode defaults to 'regular'.
fallback_uri No String The uri used to redirect the payer if 3rd party cookies are not enabled for iframes.
shipping_fee No Decimal The amount to be charged for shipping the item.
require_shipping No Boolean Default is false. If set to true then the payer will be required to enter their shipping address when paying.
prefill_info No 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","bank_account"] to accept both credit card and bank payments. ["credit_card"] to accept only credit card payments. ["bank_account"] to accept only bank account 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 funding_sources parameter is not specified, both credit card and bank account payments will be accepted in the checkout flow.
theme_object No Theme Object Structure The theme structure contains information to provide custom look-and-feel for the flows and emails.

Example:

{
  "redirect_uri": "http://www.test.com",
  "fallback_uri": "http://www.test.com",
  "shipping_fee": 2,
  "mode": "iframe",
  "require_shipping": true,
  "prefill_info": {
      "address": "main street",
      "zip": "94085",
      "country": "US"
   },
   "theme_object": {
       "name": "test",
       "primary_color": "ffffff",
       "background_color": "ffffff",
       "button_color": "000000",
       "secondary_color": "000000"
   },
  "funding_sources": ["credit_card"]
}

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 or preapproval fields. For example, if the payment method has type = "credit_card", specify "credit_card" field and do not specify "preapproval" field.

Fields:

Field Required Type Description
type Yes String (255 chars) Payment Method type. Set to 'credit_card' for tokenization
credit_card No Credit Card Structure Object that specifies the credit card id. Choose one of "credit_card" or "preapproval" fields. For example, if you are sending credit card id for tokenization, send "credit_card" field, and do not send "preapproval" field.
preapproval No Preapproval Structure Object that specifies the preapproval id. Choose one of "credit_card" or "preapproval" fields. For example, if you are sending preapproval id as a payment method, send "preapproval" field, and do not send "credit_card" field.

Example:

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

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 (only returned if a payment has been made).
email String (255 chars) The email address of the person paying (only returned if a payment has been made).
home_address String (255 chars) The home address of the person paying (only returned if a payment has been made).

Example:

{
    "name": "John Doe",
    "email": "test@o.com",
    "home_address": "Main Street"
}

Credit Card Structure

Object that specifies credit card id used for tokenization.

Fields:

Field Required Type Description
id Yes Integer Credit Card Id from /credit_card/create

Example:

{
    "id": 1234
}

Preapproval Structure

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

Fields:

Field Required Type Description
id Yes Integer Preapproval Id from /preapproval/create

Example:

{
    "id": 1234
}

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 A short message that will be included in the payment confirmation email to the payee.
to_payer No String A short message that will be included in the payment confirmation email to the payer.

Example:

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

Fee Structure

Specifies the app_fee and fee_payer parameters for a checkout.

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

Defaults to "payer".

Example:

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

Payments Prefill_Info Structure

The payments prefill_info structure contains prefill information for checkout, preapprovals, and subscription flows.

Fields:

Field Type Description
name String (255 chars) The name of the person.
email String (255 chars) The email address of the person.
phone_number String (15 chars) The phone number of the person.
address String (255 chars) The street address.
city String (30 chars) The city.
state String (2 chars) The 2-letters US state code. Only for US addresses.
region String (30 chars) The region. Only for non-US addresses when available.
zip String (10 chars) The US zip or zip-plus code. Only for US addresses.
postcode String (14 chars) The postcode. Only for non-US addresses when available.
country String (2 chars) The 2-letters ISO-3166-1 country code.

Example:

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

KYC Prefill_Info Structure

The KYC prefill_info structure contains prefill information for the KYC flow.

Fields:

Field Type Description
name String (255 chars) The name of the person.
email String (255 chars) The email address of the person.
phone_number String (15 chars) The phone number of the person.
address String (255 chars) The street address.
city String (30 chars) The city.
state String (2 chars) The 2-letters US state code. Only for US addresses.
region String (30 chars) The region. Only for non-US addresses when available.
zip String (10 chars) The US zip or zip-plus code. Only for US addresses.
postcode String (14 chars) The postcode. Only for non-US addresses when available.
country String (2 chars) The 2-letters ISO-3166-1 country code.
dob String (10 chars) The person's date of birth in the format YYYY-MM-DD.
entity_name String (255 chars) Legal name of the business or organization.
url String (255 chars) URL of business or organization's website.
description String (255 chars) Description of business or organization

Example:

{
    "name":"Bill Clerico",
    "phone_number":"555-555-5555",
    "entity_name":"My Business Inc.",
    "url":"http://www.mybusiness.com"
}
	

Theme Structure

The theme structure contains information to provide custom look-and-feel for the 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"
}

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 Number The available balance for this account (specific to the currency specified).
incoming_pending_amount Number The amount of money that being sent to the account that is still pending.
outgoing_pending_amount Number The amount of money being settled to the merchant (either via check or ACH) that is still pending.
reserved_amount Number The amount of money held in reserves.
disputed_amount Number 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 (either "check" or "ach").
withdrawal_period String (6 chars) How often money will be settled to the merchant ("daily", "weekly", or "monthly").
withdrawal_next_time String (6 chars) The unix time stamp 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:

[
  {
    "currency":"USD",
    "balance":390.50,
    "incoming_pending_amount":635.30,
    "outgoing_pending_amount":210.00,
    "reserved_amount":0,
    "disputed_amount":0,
    "withdrawal_period":"daily",
    "withdrawal_type":"ach",
    "withdrawal_next_time":1370112217,
    "withdrawal_bank_name":"WellsFargo XXXXX3102"
  },
  {
    "currency":"CAD",
    "balance":40.50,
    "incoming_pending_amount":20.30,
    "outgoing_pending_amount":70.00,
    "reserved_amount":0,
    "disputed_amount":0,
    "withdrawal_period":"daily",
    "withdrawal_type":"ach",
    "withdrawal_next_time":1370112217,
    "withdrawal_bank_name":"TD Canada XXXXX4156"
  }
]
    

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

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.

Defaults to "payer".

Example:

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

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

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 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_chargeback": 40,
    "dispute_uri": ""
}

Refund Response Structure

You can use the /checkout/refund API call to refund a charge.
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 been refunded so far.
refund_reason String (255 chars) If the payment was refunded the reason why.

Example:

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

Hosted Checkout Response Structure

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

Fields:

Field Type Description
checkout_uri String (2083 chars) The uri for the checkout.
mode String (255 chars) What mode the checkout was displayed in. The options are 'iframe' or 'regular'. Choose 'iframe' if this is an iframe checkout. Mode defaults to '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 Default is false. 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 structure (a JSON object, not a JSON serialized string) that the payer entered.
theme_object Theme Object Structure The theme structure contains information to provide custom look-and-feel for the flows and emails.

Example:

{
  "checkout_uri": "http://wepay.com/api/iframe/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": "iframe"
}