WePay gateway guide
Additional notes |
---|
WePay is unable to support direct merchants. If you represent a platform that has buyers and sellers, please sign up as a platform at WePay.com to obtain your credentials. If you are a merchant yourself, please find a platform to support your business that supports WePay. If you plan to process recurring transactions between Spreedly and WePay, you may need to contact WePay to have them enable your account. |
Due to the fact that WePay’s system restricts transaction compatibility to the version set in your WePay account’s Dashboard, and new WePay merchant accounts cannot be set to older versions, Spreedly cannot assume a single version for all of our customers. Therefore, we do not explicitly specify which version of WePay’s API our transactions conform to. This means that WePay assumes that we are using the version that is set in your WePay account Dashboard. Therefore: - When you create an account with WePay, please contact us to verify that we support the version your account is locked to. We will do our best to ensure that our system is compatible with newly released versions. - You are encouraged to update the version set in your Dashboard as we continue to ensure compatiblity with the newest version. - For more information, see WePay’s API versions page. |
Adding a WePay gateway
To add a WePay gateway:
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>wepay</gateway_type>
<client_id>your_client_id</client_id>
<account_id>your_account_id</account_id>
<access_token>your_access_token</access_token>
<client_secret>your_client_secret</client_secret>
</gateway>'
<gateway>
<token>nT4TG65raS75nxvbj4WATifUFX</token>
<gateway_type>wepay</gateway_type>
<name>WePay</name>
<description nil="true"/>
<client_id>your_client_id</client_id>
<account_id>your_account_id</account_id>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_verify type="boolean">false</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_disburse type="boolean">false</supports_disburse>
</characteristics>
<credentials>
<credential>
<name>client_id</name>
<value>your_client_id</value>
</credential>
<credential>
<name>account_id</name>
<value>your_account_id</value>
</credential>
</credentials>
<gateway_specific_fields>
<gateway_specific_field>version</gateway_specific_field>
<gateway_specific_field>callback_uri</gateway_specific_field>
<gateway_specific_field>fee_payer</gateway_specific_field>
<gateway_specific_field>application_fee</gateway_specific_field>
<gateway_specific_field>type</gateway_specific_field>
<gateway_specific_field>unique_id</gateway_specific_field>
<gateway_specific_field>original_device</gateway_specific_field>
<gateway_specific_field>risk_token</gateway_specific_field>
<gateway_specific_field>long_description</gateway_specific_field>
<gateway_specific_field>payer_rbits</gateway_specific_field>
<gateway_specific_field>transaction_rbits</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<created_at type="dateTime">2018-06-19T17:08:04Z</created_at>
<updated_at type="dateTime">2018-06-19T17:08:04Z</updated_at>
</gateway>
Gateway specific fields
When interacting with a WePay gateway to run transactions, there are some gateway specific fields you can specify.
You can specify a version
which will be send in the API version header of the request, overriding the version set in your WePay account’s Dashboard. Note however that it will only succeed if it matches, or is one step ahead of the version set in your Dashboard, and that we may not yet support features or changes in a new version. You can use this to test out any new features or changes and report issues to us. For more information, see Additional notes above, and WePay’s API versions page.
You can specify a callback_uri
which can be used to listen for WePay’s Instant Payment Notifications (IPNs).
You can specify an application_fee
and fee_payer
to inform WePay as to who will pay the fees (WePay’s fees and any app fees).
You can specify the type
to inform WePay as to the checkout type (service, donation, etc).
You can specify a unique_id
to prevent duplicate payments from being recorded.
You can specify a original_device
to pass in the user-agent or IMEI of the user.
You can specify risk_token
to be added as part of WePay risk headers. The client ip is mapped from the top level Spreedly request element.
You can specify a long_description
to pass in a long description for the transaction.
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
<gateway_specific_fields>
<wepay>
<version>2017-05-31</version>
<callback_uri>http://example.com/myipn/callback</callback_uri>
<fee_payer>payee</fee_payer>
<application_fee>10</application_fee>
<type>EVENT</type>
<unique_id>un33qu3</unique_id>
<original_device>Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405</original_device>
<risk_token>123e4567-e89b-12d3-a456-426655440000</risk_token>
<long_description>A long descript for the transaction</long_description>
</wepay>
</gateway_specific_fields>
</transaction>'
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-09-07T19:52:58Z</created_at>
<updated_at type="dateTime">2017-09-07T19:52:59Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>46odcc1hjhVyxaVwYlNrVUhC64l</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields>
<wepay>
<version>2017-05-31</version>
<callback_uri>http://example.com/myipn/callback</callback_uri>
<fee_payer>payee</fee_payer>
<application_fee>10</application_fee>
<type>EVENT</type>
<unique_id>un33qu3</unique_id>
<original_device>Mozilla/5.0 (iPad; U; CPU OS 3_2_1 like Mac OS X; en-us) AppleWebKit/531.21.10 (KHTML, like Gecko) Mobile/7B405</original_device>
<risk_token>123e4567-e89b-12d3-a456-426655440000</risk_token>
<long_description>A long descript for the transaction</long_description>
</wepay>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>50</gateway_transaction_id>
<gateway_latency_ms type="integer">0</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>87h43q6wY1kKxRE29giYrTl3PyZ</gateway_token>
<shipping_address>
<name>Torrey Emard</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-09-07T19:52:58Z</created_at>
<updated_at type="dateTime">2017-09-07T19:52:59Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>UljnljuNX2VIcl8GziRUjUsZQ2y</token>
<created_at type="dateTime">2017-08-24T14:05:18Z</created_at>
<updated_at type="dateTime">2017-08-24T14:05:18Z</updated_at>
<email nil="true"/>
<data nil="true"/>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Torrey</first_name>
<last_name>Emard</last_name>
<month type="integer">4</month>
<year type="integer">2020</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Torrey Emard</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
WePay OAuth account creation
WePay’s OAuth Support allows you to obtain permission from your customer to access their WePay account. At the end of the OAuth process, you’ll be given an access_token
. Once you have that access_token
, you can create a gateway by passing it in like so:
curl https://core.spreedly.com/v1/gateways.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<gateway>
<gateway_type>wepay</gateway_type>
<client_id>your_client_id</client_id>
<account_id>your_account_id</account_id>
<access_token>The Access Token received from the OAuth process</access_token>
<client_secret>your_client_secret</client_secret>
</gateway>'
<gateway>
<token>MCwcYtw9qGp5Iq3Nh2CgNVvaZUI</token>
<gateway_type>wepay</gateway_type>
<name>WePay</name>
<description nil="true"/>
<client_id>your_client_id</client_id>
<account_id>your_account_id</account_id>
<characteristics>
<supports_purchase type="boolean">true</supports_purchase>
<supports_authorize type="boolean">true</supports_authorize>
<supports_capture type="boolean">true</supports_capture>
<supports_credit type="boolean">true</supports_credit>
<supports_general_credit type="boolean">false</supports_general_credit>
<supports_void type="boolean">true</supports_void>
<supports_verify type="boolean">false</supports_verify>
<supports_reference_purchase type="boolean">true</supports_reference_purchase>
<supports_purchase_via_preauthorization type="boolean">false</supports_purchase_via_preauthorization>
<supports_offsite_purchase type="boolean">false</supports_offsite_purchase>
<supports_offsite_authorize type="boolean">false</supports_offsite_authorize>
<supports_3dsecure_purchase type="boolean">false</supports_3dsecure_purchase>
<supports_3dsecure_authorize type="boolean">false</supports_3dsecure_authorize>
<supports_store type="boolean">true</supports_store>
<supports_remove type="boolean">false</supports_remove>
<supports_fraud_review type="boolean">false</supports_fraud_review>
<supports_disburse type="boolean">false</supports_disburse>
</characteristics>
<credentials>
<credential>
<name>client_id</name>
<value>your_client_id</value>
</credential>
<credential>
<name>account_id</name>
<value>your_account_id</value>
</credential>
</credentials>
<gateway_specific_fields>
<gateway_specific_field>callback_uri</gateway_specific_field>
<gateway_specific_field>fee_payer</gateway_specific_field>
<gateway_specific_field>application_fee</gateway_specific_field>
<gateway_specific_field>type</gateway_specific_field>
<gateway_specific_field>unique_id</gateway_specific_field>
<gateway_specific_field>original_device</gateway_specific_field>
<gateway_specific_field>risk_token</gateway_specific_field>
<gateway_specific_field>long_description</gateway_specific_field>
<gateway_specific_field>payer_rbits</gateway_specific_field>
<gateway_specific_field>transaction_rbits</gateway_specific_field>
</gateway_specific_fields>
<payment_methods>
<payment_method>credit_card</payment_method>
</payment_methods>
<state>retained</state>
<redacted type="boolean">false</redacted>
<created_at type="dateTime">2017-07-27T17:51:19Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:19Z</updated_at>
</gateway>
Sending risk information
WePay’s risk API provides a way to communicate risk related information with your transactions. If you are using or required to use the risk API, you can pass the payer_rbits
and transaction_rbits
information via their respective gateway specific fields. Note that we will pass through exactly what we receive without any processing on Spreedly’s end.
Additionally, to make this easier for user’s integrated via XML, the rbits JSON data can be passed within CDATA tags enabling you to bypass reconstructing the same data as XML. Just pass it in directly as a single string. However if you use the JSON format, pass the JSON as is into gateway specific field.
Transactions rbits XML example
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.xml \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/xml' \
-d '<transaction>
<payment_method_token>56wyNnSmuA6CWYP7w0MiYCVIbW6</payment_method_token>
<amount>100</amount>
<currency_code>USD</currency_code>
<gateway_specific_fields>
<wepay>
<transaction_rbits>
<![CDATA[ [ { "receive_time":123456789, "type":"transaction_details", "source":"user", "properties":{ "itemized_receipt":[ { "description":"Custom development work", "item_price":1000.00, "quantity":1, "amount":10000.00, "currency":"USD" }, { "description":"Custom design work", "item_price":300, "quantity":4, "amount":1200, "currency":"USD" } ], "note": "Thanks for your business!" } } ]]]>
</transaction_rbits>
</wepay>
</gateway_specific_fields>
</transaction>'
<transaction>
<on_test_gateway type="boolean">true</on_test_gateway>
<created_at type="dateTime">2017-07-27T17:51:20Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:20Z</updated_at>
<succeeded type="boolean">true</succeeded>
<state>succeeded</state>
<token>PeF1g1NDGmsK2E1yqyyL3xBqdPD</token>
<transaction_type>Purchase</transaction_type>
<order_id nil="true"/>
<ip nil="true"/>
<description nil="true"/>
<email nil="true"/>
<merchant_name_descriptor nil="true"/>
<merchant_location_descriptor nil="true"/>
<gateway_specific_fields>
<wepay>
<transaction_rbits>
[ { "receive_time":123456789, "type":"transaction_details", "source":"user", "properties":{ "itemized_receipt":[ { "description":"Custom development work", "item_price":1000.00, "quantity":1, "amount":10000.00, "currency":"USD" }, { "description":"Custom design work", "item_price":300, "quantity":4, "amount":1200, "currency":"USD" } ], "note": "Thanks for your business!" } } ]
</transaction_rbits>
</wepay>
</gateway_specific_fields>
<gateway_specific_response_fields>
</gateway_specific_response_fields>
<gateway_transaction_id>67</gateway_transaction_id>
<gateway_latency_ms type="integer">23</gateway_latency_ms>
<amount type="integer">100</amount>
<currency_code>USD</currency_code>
<retain_on_success type="boolean">false</retain_on_success>
<payment_method_added type="boolean">false</payment_method_added>
<message key="messages.transaction_succeeded">Succeeded!</message>
<gateway_token>T11bJAANtTWnxl36GYjKWvbNK0g</gateway_token>
<shipping_address>
<name>Newfirst Newlast</name>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
</shipping_address>
<response>
<success type="boolean">true</success>
<message>Successful purchase</message>
<avs_code nil="true"/>
<avs_message nil="true"/>
<cvv_code nil="true"/>
<cvv_message nil="true"/>
<pending type="boolean">false</pending>
<result_unknown type="boolean">false</result_unknown>
<error_code></error_code>
<error_detail nil="true"/>
<cancelled type="boolean">false</cancelled>
<fraud_review nil="true"/>
<created_at type="dateTime">2017-07-27T17:51:20Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:20Z</updated_at>
</response>
<api_urls>
</api_urls>
<payment_method>
<token>1rpKvP8zOUhj4Y9EDrIoIYQzzD5</token>
<created_at type="dateTime">2017-06-26T17:04:38Z</created_at>
<updated_at type="dateTime">2017-07-27T17:51:20Z</updated_at>
<email>[email protected]</email>
<data>
<my_payment_method_identifier>448</my_payment_method_identifier>
<extra_stuff>
<some_other_things>Can be anything really</some_other_things>
</extra_stuff>
</data>
<storage_state>retained</storage_state>
<test type="boolean">true</test>
<last_four_digits>1111</last_four_digits>
<first_six_digits>411111</first_six_digits>
<card_type>visa</card_type>
<first_name>Newfirst</first_name>
<last_name>Newlast</last_name>
<month type="integer">3</month>
<year type="integer">2032</year>
<address1 nil="true"/>
<address2 nil="true"/>
<city nil="true"/>
<state nil="true"/>
<zip nil="true"/>
<country nil="true"/>
<phone_number nil="true"/>
<company nil="true"/>
<full_name>Newfirst Newlast</full_name>
<eligible_for_card_updater nil="true"/>
<shipping_address1 nil="true"/>
<shipping_address2 nil="true"/>
<shipping_city nil="true"/>
<shipping_state nil="true"/>
<shipping_zip nil="true"/>
<shipping_country nil="true"/>
<shipping_phone_number nil="true"/>
<payment_method_type>credit_card</payment_method_type>
<errors>
</errors>
<verification_value></verification_value>
<number>XXXX-XXXX-XXXX-1111</number>
<fingerprint>e3cef43464fc832f6e04f187df25af497994</fingerprint>
</payment_method>
</transaction>
Transaction rbits JSON example
curl https://core.spreedly.com/v1/gateways/LlkjmEk0xNkcWrNixXa1fvNoTP4/purchase.json \
-u 'C7cRfNJGODKh4Iu5Ox3PToKjniY:4UIuWybmdythfNGPqAqyQnYha6s451ri0fYAo4p3drZUi7q2Jf4b7HKg8etDtoKJ' \
-H 'Content-Type: application/json' \
-d '{
"transaction": {
"payment_method_token": "56wyNnSmuA6CWYP7w0MiYCVIbW6",
"currency_code": "USD",
"amount": 5000,
"gateway_specific_fields": {
"wepay": {
"transaction_rbits": [
{
"receive_time": 123456789,
"type": "transaction_details",
"source": "user",
"properties": {
"itemized_receipt": [
{
"description": "Custom development work",
"item_price": 1000.00,
"quantity": 1,
"amount": 10000.00,
"currency": "USD"
},
{
"description": "Custom design work",
"item_price": 300,
"quantity": 4,
"amount": 1200,
"currency": "USD"
}
],
"note": "Thank you for your business!"
}
}
]
}
}
}
}'
{
"transaction": {
"on_test_gateway": true,
"created_at": "2017-07-27T17:51:20Z",
"updated_at": "2017-07-27T17:51:20Z",
"succeeded": true,
"state": "succeeded",
"token": "NQkRFXwNR4n1syIdGwbKWfFV3dH",
"transaction_type": "Purchase",
"order_id": null,
"ip": null,
"description": null,
"email": null,
"merchant_name_descriptor": null,
"merchant_location_descriptor": null,
"gateway_specific_fields": {
"wepay": {
"transaction_rbits": [
{
"receive_time": 123456789,
"type": "transaction_details",
"source": "user",
"properties": {
"itemized_receipt": [
{
"description": "Custom development work",
"item_price": 1000.0,
"quantity": 1,
"amount": 10000.0,
"currency": "USD"
},
{
"description": "Custom design work",
"item_price": 300,
"quantity": 4,
"amount": 1200,
"currency": "USD"
}
],
"note": "Thank you for your business!"
}
}
]
}
},
"gateway_specific_response_fields": {
},
"gateway_transaction_id": "57",
"gateway_latency_ms": 22,
"amount": 5000,
"currency_code": "USD",
"retain_on_success": false,
"payment_method_added": false,
"message_key": "messages.transaction_succeeded",
"message": "Succeeded!",
"gateway_token": "T11bJAANtTWnxl36GYjKWvbNK0g",
"response": {
"success": true,
"message": "Successful purchase",
"avs_code": null,
"avs_message": null,
"cvv_code": null,
"cvv_message": null,
"pending": false,
"result_unknown": false,
"error_code": "",
"error_detail": null,
"cancelled": false,
"fraud_review": null,
"created_at": "2017-07-27T17:51:20Z",
"updated_at": "2017-07-27T17:51:20Z"
},
"shipping_address": {
"name": "Newfirst Newlast",
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null
},
"api_urls": [
{
"referencing_transaction": [
]
}
],
"payment_method": {
"token": "1rpKvP8zOUhj4Y9EDrIoIYQzzD5",
"created_at": "2017-06-26T17:04:38Z",
"updated_at": "2017-07-27T17:51:18Z",
"email": "[email protected]",
"data": {
"my_payment_method_identifier": "448",
"extra_stuff": {
"some_other_things": "Can be anything really"
}
},
"storage_state": "retained",
"test": true,
"last_four_digits": "1111",
"first_six_digits": "411111",
"card_type": "visa",
"first_name": "Newfirst",
"last_name": "Newlast",
"month": 3,
"year": 2032,
"address1": null,
"address2": null,
"city": null,
"state": null,
"zip": null,
"country": null,
"phone_number": null,
"company": null,
"full_name": "Newfirst Newlast",
"eligible_for_card_updater": null,
"shipping_address1": null,
"shipping_address2": null,
"shipping_city": null,
"shipping_state": null,
"shipping_zip": null,
"shipping_country": null,
"shipping_phone_number": null,
"payment_method_type": "credit_card",
"errors": [
],
"fingerprint": "e3cef43464fc832f6e04f187df25af497994",
"verification_value": "",
"number": "XXXX-XXXX-XXXX-1111"
}
}
}
Updated 5 months ago