.. meta:: :description: /mapi/v1/sale AlbionPay mobile API endpoint: initiate a card sale from a mobile app via the mAPI v1 interface with 3DS support. .. _mapi_v1_sale: /mapi/v1/sale ============================ .. role:: ex .. role:: code Introduction ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Application initiates a transaction by sending :code:`HTTPS POST` request by using :ref:`URL` and the :ref:`parameters` specified below. Use :ref:`HMAC-SHA1` for authentication. .. _mapi/api/sale: API URLs ^^^^^^^^ .. note:: | The path in API URL should not be hardcoded, as it may be changed in future. .. list-table:: :widths: 50, 50 :header-rows: 1 :class: longtable * - Integration - Production * - :ex:`https://sandbox.albionpay.com/paynet/mapi/v1/sale/ENDPOINTID` - :ex:`https://gate.albionpay.com/paynet/mapi/v1/sale/ENDPOINTID` .. _mapi/parameters/sale: Request Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. note:: | \* leading and trailing whitespace in input parameters will be omitted | Please note the following characters must be escaped in the parameter values: :code:`&` :code:`+` :code:`\\`. .. list-table:: :widths: 30 50 20 :header-rows: 1 :class: longtable * - Parameter Name - Description - Value * - :code:`client_orderid` - Unique order identifier assigned by Connecting Party. - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 128 * - :code:`order_desc` - Brief order description - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 64k * - :code:`first_name` - Payer's first name. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 50 * - :code:`last_name` - Payer’s last name - | ``Necessity``: Optional | ``Type``: String | ``Length``: 50 * - :code:`ssn` - Last four digits of the payer’s social security number. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 32 * - :code:`birthday` - Payer’s date of birth, in the format YYYYMMDD. - | ``Necessity``: Optional | ``Type``: Numeric | ``Length``: 8 * - :code:`address1` - Payer’s address line 1. (Please note that in some cases it is not possible to send address length more than 50 characters. Please contact your manager for more details.) - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 256 * - :code:`city` - Payer’s city. - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 50 * - :code:`state` - Payer’s state. Please see :ref:`Mandatory State codes` for a list of valid state codes. Required for USA, Canada and Australia. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 2 * - :code:`zip_code` - Payer’s ZIP code - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 10 * - :code:`country` - Payer’s country. Please see :ref:`Country codes` for a list of valid country codes. - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 2 * - :code:`phone` - Payer’s full international phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 15 * - :code:`cell_phone` - Payer’s full international cell phone number, including country code. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 15 * - :code:`email` - Payer’s e-mail address. - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 50 * - :code:`purpose` - Destination to where the payment goes. It is useful for the Connecting Partys who let their payers to top up their accounts with bank card (Mobile phone accounts, game accounts etc.). Sample values are: :ex:`+9999999999`; :ex:`mail@example.com` etc. This value can be used by the fraud monitoring system. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 128 * - :code:`amount` - Amount to be charged. The amount has to be specified in the highest units with :ex:`.` delimiter. For instance, :ex:`10.5` for USD means 10 US Dollars and 50 Cents - | ``Necessity``: Mandatory | ``Type``: Numeric | ``Length``: 10 * - :code:`currency` - Currency the transaction is charged in (See: :ref:`Currency codes`). Sample values are: :ex:`USD` for US Dollar :ex:`EUR` for European Euro - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 3 * - :code:`cvv2` - Customer’s CVV2 code. CVV2 (Card Verification Value) is a three- or four-digit number AFTER the credit card number in the signature area of the card. It used if acquirer provides only E-Commerce connection - | ``Necessity``: Optional | ``Type``: Numeric | ``Lenght``: 3-4 * - :code:`ipaddress` - Payer’s IP address, included for fraud screening purposes. - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 20 * - :code:`encrypted-type` - Type of the encryption. This depends on mPOS model - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: 32 * - :code:`encrypted-data` - Card tracks data encrypted using :ex:`encrypted-type` encryption and encoded using HEX encoding. For more info contact support - | ``Necessity``: Mandatory | ``Type``: String | ``Length``: - * - :code:`server_callback_url` - | URL, where the transaction status is sent to. | Connecting Party may use server callback URL for custom processing of the transaction completion, e.g. to collect payment data in the Connecting Party’s information system. For the list of parameters which come along with server callback to :ex:`server_callback_url` refer to :ref:`Connecting Party callback parameters`. - | ``Necessity``: Optional | ``Type``: String | ``Length``: 1024 Request Authentication Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ | To make sure that request is authorized by Connecting Party, all requests must be signed. MAPI works with OAuth 1.0a :ex:`HMAC-SHA1` signature as it is a well-established and supported in the client libraries. | MAPI supports only the signature part and does not support a full-blown OAuth. Connecting Party control key is used as a secret key. | Below is an example of how to make a signed request in Java with help of `scribe library `_: .. highlight:: java :: import org.scribe.builder.api.DefaultApi10a; import org.scribe.model.*; import org.scribe.oauth.OAuth10aServiceImpl; import org.scribe.oauth.OAuthService; import org.scribe.services.HMACSha1SignatureService; import org.scribe.services.SignatureService; import java.util.Map; public class App { public String doPost(String url, Mapparameters) { OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND, SignatureType.Header, null,null); OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config); OAuthRequest request = new OAuthRequest(Verb.POST,url); for (Map.Entry < String,String > entry :parameters.entrySet()){ request.addBodyParameter(entry.getKey(), entry.getValue()); } // empty token for 'two-legged' Token token = new Token("", ""); service.signRequest(token, request); Response response = request.send(); return response.getBody(); } private static class HmacSha1Mapi extends DefaultApi10a { @Override public String getRequestTokenEndpoint() { return null; // not used } @Override public String getAccessTokenEndpoint() { return null; //not used } @Override public String getAuthorizationUrl(Token requestToken) { return null; // not used } @Override public SignatureService getSignatureService() { return new HMACSha1SignatureService(); } } } .. Request Signing with RSA-SHA1 Signature Method .. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. .. This signature method doesn't require shared secret. Merchant just uses his private key to sign requests. Here is an example of how to make a signed request in Java with help of `scribe library `_: .. .. .. highlight:: java .. :: .. .. import com.payneteasy.tlv.HexUtil; .. import org.scribe.builder.api.DefaultApi10a; .. import org.scribe.model.*; .. import org.scribe.oauth.OAuth10aServiceImpl; .. import org.scribe.oauth.OAuthService; .. import org.scribe.services.HMACSha1SignatureService; .. import org.scribe.services.SignatureService; .. .. import java.nio.charset.StandardCharsets; .. import java.util.HashMap; .. import java.util.Map; .. .. public class App .. { .. public String doPost(String url, Map parameters) throws ConnectionIOException, ConnectionTimeoutException .. { .. OAuthConfig config = new OAuthConfig(apiToken, merchantControlKey, OAuthConstants.OUT_OF_BAND, SignatureType.Header, null,null); .. OAuthService service = new OAuth10aServiceImpl(new HmacSha1Mapi(), config); .. OAuthRequest request = new OAuthRequest(Verb.POST, url); .. for (Map.Entry entry : parameters.entrySet()) { .. request.addBodyParameter(entry.getKey(), entry.getValue()); .. } .. // empty token for 'two-legged' .. Token token = new Token("", ""); .. service.signRequest(token, request); .. Response response = request.send(); .. return response.getBody(); .. } .. .. private static class HmacSha1Mapi extends DefaultApi10a { .. @Override .. public String getRequestTokenEndpoint() { .. return null; // not used .. } .. .. @Override .. public String getAccessTokenEndpoint() { .. return null; //not used .. } .. .. @Override .. public String getAuthorizationUrl(Token requestToken) { .. return null; // not used .. } .. .. @Override .. public SignatureService getSignatureService() { .. return new HMACSha1SignatureService(); .. } .. } .. } .. _sale-form_response_parameters: Response Parameters ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. list-table:: :widths: 25, 75 :header-rows: 1 :class: longtable * - Parameter name - Description * - :code:`type` - The type of response. May be :ex:`async-form-response`, :ex:`validation-error`, :ex:`error`. If type equals :ex:`validation-error` or :ex:`error`, :ex:`error-message` and :ex:`error-code` parameters contain error details. * - :code:`status` - See :ref:`status_list` for details * - :code:`paynet-order-id` - Order id assigned to the order by gate.albionpay.com * - :code:`merchant-order-id` - Connecting Party order id * - :code:`serial-number` - Unique number assigned by gate.albionpay.com server to particular request from the Connecting Party. * - :code:`error-message` - If status is :ex:`declined` or :ex:`error` this parameter contains the reason for decline or error details * - :code:`error-code` - The error code in case of :ex:`declined` or :ex:`error` status Google Pay Request Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Once a Google Pay token is retrieved, it may look like follows: .. code-block:: json { "signature": "MEUCIQCOH1uW2LaQheaE4bg074mqd3QpFIx/BJxG/OGMEhhDqwIgPb6XzlwDwBM+SLzk2HYnAy0h/Pkps8l8Bn13AVc9hQQ\u003d", "intermediateSigningKey": { "signedKey": "{"keyValue":"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEiZi3I+5g0xH3kOXMxiNyoOMMRwU7sD+/qks15AdgSU5+xH2PTFwe9yCQLzn4DSdjo3QKIyc+c5fUG1dkasBvKw\\u003d\\u003d","keyExpiration":"1649766119579"}", "signatures": [ "MEYCIQDLUKwcyf9AAqyJ6WSLrT5jG+Hd4iKvoXxaayvFUerX8wIhAMzHqN1xyAIRhznjLkkUAOQgbg7cUltK0FH1hvRL7CAN" ] }, "protocolVersion": "ECv2", "signedMessage": "{"encryptedMessage":"EOpG0NNX9OpyYzlR5FEe6CMNf4pkeJvEhOOOG94cBD+y1x22LdGE55Le2gBRI3mFRCusQDaQtyCS5PvoLp0/urpWNr8xTxW/EwxjnqkYgUBRFGOmbJQAceA/7MAlPu9w4gs0COY2akgurdCbLQkLasTSc5e/ i6GWmdiXqWAWM8JrNBVklpYnFek3FCeK3W23mYHntedCLyTTPVmbUeMQ4n8rhgzo+8fiWNjKywLjVZlJ2o+oCNxhMVfhG74GdWvob2TfE1uoeXOCXOH02u8towOOvR2fqnAkIBDUfpiUSjpW7MmDTJyYIewc W4EoWGTE6A+pEyI8jTbA4Y0box39exJbNthQsThqXg5OKJOEDcMNYBPg/lbyNQfY8NjvBMA7fB//QiZqIu8WgZFfSiMJ+j4uXHdCDfLT9biw4pde7bkRuH/Uofd1CabifhQSu64SeEEkj0r87wEY55sNr8Kz SCAwwOgQP0XYlt/t0A5KT9k172I84WtiWQYr/UNuIVURiH8x08e8Ihx9Nvkgx+Gz/ZyUVQH9RXjEXDRNvm63sSiUMB1TlY9PiMKO0451Uw2yw30c/8SzyKByPYtNdHwmd6iAhfoQSpJAKMTwhYMmKFZC+b8K HKbx8Ge+NVKv2GpCLwy0WL4wvqWNPk21Jzc0bFcnzztafdTPbbEB1pfY","ephemeralPublicKey":"BGVn0SZ1J5pDZlInHve5nj1Ybj+C0olFcTygynSqU8YqKaZs8ZdHQjVlISrRI10PmskgZSMH YXdkM0k+/D8/o0o\\u003d","tag":"II0dhcOZtYl26Yln3GNSXTK4yalRylKsKj71RyjZfFM\\u003d"}" } Make HEX from the token: .. code-block:: text 7B0A2020227369676E6174757265223A20224D4555434951434F48317557324C6151686561453462673037346D71643351704649782F424A78472F4F474D4568684471774967506236587A6C774477424D2B534C7A6B3248596E417930682F506B707338 6C38426E3133415663396851515C7530303364222C0A202022696E7465726D6564696174655369676E696E674B6579223A207B0A20202020227369676E65644B6579223A20227B5C226B657956616C75655C223A5C224D466B77457759484B6F5A497A6A 3043415159494B6F5A497A6A30444151634451674145695A6933492B3567307848336B4F584D78694E796F4F4D4D5277553773442B2F716B7331354164675355352B7848325054467765397943514C7A6E344453646A6F33514B4979632B633566554731 646B617342764B775C5C75303033645C5C75303033645C222C5C226B657945787069726174696F6E5C223A5C22313634393736363131393537395C227D222C0A20202020227369676E617475726573223A205B0A202020202020224D4559434951444C55 4B7763796639414171794A3657534C7254356A472B486434694B766F587861617976465565725838774968414D7A48714E317879414952687A6E6A4C6B6B55414F516762673763556C744B304648316876524C3743414E220A202020205D0A20207D2C0A 20202270726F746F636F6C56657273696F6E223A202245437632222C0A2020227369676E65644D657373616765223A20227B5C22656E637279707465644D6573736167655C223A5C22454F7047304E4E58394F7079597A6C523546456536434D4E663470 6B654A7645684F4F4F4739346342442B79317832324C64474535354C653267425249336D465243757351446151747943533550766F4C70302F757270574E7238785478572F4577786A6E716B596755425246474F6D624A51416365412F374D416C507539 7734677330434F5932616B6775726443624C516B4C617354536335652F693647576D646958715741574D384A724E42566B6C70596E46656B334643654B335732336D59486E746564434C79545450566D6255654D51346E387268677A6F2B386669574E6A 4B79774C6A565A6C4A326F2B6F434E78684D566668473734476457766F623254664531756F65584F43584F4830327538746F774F4F76523266716E416B4942445566706955536A7057374D6D44544A7959496577635734456F5747544536412B70457949 386A546241345930626F78333965784A624E746851735468715867354F4B4A4F4544634D4E594250672F6C62794E516659384E6A76424D413766422F2F51695A7149753857675A466653694D4A2B6A34755848644344664C54396269773470646537626B 5275482F556F6664314361626966685153753634536545456B6A307238377745593535734E72384B7A53434177774F6751503058596C742F743041354B54396B313732493834577469575159722F554E75495655526948387830386538496878394E766B 67782B477A2F5A79555651483952586A455844524E766D3633735369554D4231546C593950694D4B4F3034353155773279773330632F38537A794B42795059744E6448776D6436694168666F5153704A414B4D547768594D6D4B465A432B62384B484B62 783847652B4E564B76324770434C777930574C34777671574E506B32314A7A63306246636E7A7A74616664545062624542317066595C222C5C22657068656D6572616C5075626C69634B65795C223A5C224247566E30535A314A3570445A6C496E487665 356E6A3159626A2B43306F6C4663547967796E5371553859714B615A73385A6448516A566C49537252493130506D736B675A534D485958646B4D306B2B2F44382F6F306F5C5C75303033645C222C5C227461675C223A5C224949306468634F5A74596C32 36596C6E33474E5358544B3479616C52796C4B734B6A373152796A5A66464D5C5C75303033645C227D220A7D Form a request setting :ex:`encrypted-data` equals token HEX and :ex:`encrypted-type=googlepay`: .. code-block:: http POST paynet/mapi/v1/sale/27764 HTTP/1.1 Host: sandbox.albionpay.com User-Agent: curl/7.83.0 Accept: */* Authorization: OAuth realm="",oauth_version="1.0",oauth_consumer_key="test_merchant14",oauth_signature_method="HMAC-SHA1",oauth_signature="hSXMSUPP%2FIGYOOWpU4LVx0mu7SA%3D" Content-Length: 108 Content-Type: application/x-www-form-urlencoded Connection: close client_orderid=123098 &cvv2=XXX &amount=114.94 &ipaddress=115.135.52.242 &state= ¤cy=USD &phone=+6072344354 &zip_code=81200 &order_desc=Super product 1 &email=francislusaikun@yahoo.com &country=MY &city=Johor Bahru &address1=11 Jalan Lurah 6 Kg. Kempas Baru &redirect_url=http://MERCHANT_SITE/payment_update/123098/ &encrypted-type=googlepay &encrypted-data=7B0A2020227369676E6174757265223A20224D4555434951434F48317557324C6151686561453462673037346D71643351704649782F424A78472F4F474D4568684471774967506236587A6C774477424D2B534C7A6B3248596E4179 30682F506B7073386C38426E3133415663396851515C7530303364222C0A202022696E7465726D6564696174655369676E696E674B6579223A207B0A20202020227369676E65644B6579223A20227B5C226B657956616C75655C223A5C224D466B774577 59484B6F5A497A6A3043415159494B6F5A497A6A30444151634451674145695A6933492B3567307848336B4F584D78694E796F4F4D4D5277553773442B2F716B7331354164675355352B7848325054467765397943514C7A6E344453646A6F33514B4979 632B633566554731646B617342764B775C5C75303033645C5C75303033645C222C5C226B657945787069726174696F6E5C223A5C22313634393736363131393537395C227D222C0A20202020227369676E617475726573223A205B0A202020202020224D 4559434951444C554B7763796639414171794A3657534C7254356A472B486434694B766F587861617976465565725838774968414D7A48714E317879414952687A6E6A4C6B6B55414F516762673763556C744B304648316876524C3743414E220A202020 205D0A20207D2C0A20202270726F746F636F6C56657273696F6E223A202245437632222C0A2020227369676E65644D657373616765223A20227B5C22656E637279707465644D6573736167655C223A5C22454F7047304E4E58394F7079597A6C52354645 6536434D4E6634706B654A7645684F4F4F4739346342442B79317832324C64474535354C653267425249336D465243757351446151747943533550766F4C70302F757270574E7238785478572F4577786A6E716B596755425246474F6D624A5141636541 2F374D416C5075397734677330434F5932616B6775726443624C516B4C617354536335652F693647576D646958715741574D384A724E42566B6C70596E46656B334643654B335732336D59486E746564434C79545450566D6255654D51346E387268677A 6F2B386669574E6A4B79774C6A565A6C4A326F2B6F434E78684D566668473734476457766F623254664531756F65584F43584F4830327538746F774F4F76523266716E416B4942445566706955536A7057374D6D44544A7959496577635734456F574754 4536412B70457949386A546241345930626F78333965784A624E746851735468715867354F4B4A4F4544634D4E594250672F6C62794E516659384E6A76424D413766422F2F51695A7149753857675A466653694D4A2B6A34755848644344664C54396269 773470646537626B5275482F556F6664314361626966685153753634536545456B6A307238377745593535734E72384B7A53434177774F6751503058596C742F743041354B54396B313732493834577469575159722F554E754956555269483878303865 38496878394E766B67782B477A2F5A79555651483952586A455844524E766D3633735369554D4231546C593950694D4B4F3034353155773279773330632F38537A794B42795059744E6448776D6436694168666F5153704A414B4D547768594D6D4B465A 432B62384B484B62783847652B4E564B76324770434C777930574C34777671574E506B32314A7A63306246636E7A7A74616664545062624542317066595C222C5C22657068656D6572616C5075626C69634B65795C223A5C224247566E30535A314A3570 445A6C496E487665356E6A3159626A2B43306F6C4663547967796E5371553859714B615A73385A6448516A566C49537252493130506D736B675A534D485958646B4D306B2B2F44382F6F306F5C5C75303033645C222C5C227461675C223A5C2249493064 68634F5A74596C3236596C6E33474E5358544B3479616C52796C4B734B6A373152796A5A66464D5C5C75303033645C227D220A7D Google Pay Response Example ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ .. code-block:: http type=async-response &serial-number=00000000-0000-0000-0000-0000000624e8 &merchant-order-id=59e1e3ca-5d44-11e1-b3d6-002522b853b4 &paynet-order-id=94935