Back to top

Web Service API

Customer 

Delete a Customer 

Delete a Customer
/api/v1/customers/{identifier}

Path Parameters:

NameTypeRequirementDescription
identifierstring-The identifier of the customer (aka token)
  • Response  204
  • Body
    {'code': 204, 'message': 'No Content', 'errors': null}
  • Response  403
  • Body
    {'code': 403, 'message': 'You do not have the necessary permissions', 'errors': null}
  • Response  404
  • Body
    {'code': 404, 'message': 'Not Found', 'errors': null}
  • Response  409
  • Body
    {'code': 409, 'message': 'Conflict', 'errors': null}

Get Info 

Get Info
/epayment/api/customer/info/{merchantConfigKey}/{token}/

Path Parameters:

NameTypeRequirementDescription
merchantConfigKeystring-Merchant config key
tokenstring-corresponding token
  • Response  200
  • Body
    {
    "stored_customer_email": "your_email@host.com",
    "token": "mncal99u2lkj2uo24nasdzuz2287249872lsss"
}
  • Response  400
  • Body
    no token|merchantConfigKey provided
  • Response  400
  • Body
    no valid merchantConfigKey provided

Create a new Customer 

Create a new Customer
/api/v1/customers/

POST Parameters:

NameTypeRequirementRequiredDescription
emailstring-trueemail address of the customer
stored_[_a-z0-9]*string-falsecustomer parameter
merchant_identifierstring-truemerchant identifier
  • Response  201
  • Body
    {'code': 201, 'message': 'Created', 'errors': null}
  • Response  403
  • Body
    {'code': 403, 'message': 'You do not have the necessary permissions', 'errors': null}
  • Response  409
  • Body
    {'code': 409, 'message': 'Customer with email ... of merchant ... already exists', 'resource': '<resource uri>'}

Retrieve data of the customer identified by the specified identifier 

Retrieve data of the customer identified by the specified identifier
/api/v1/customers/{identifier}

Other allowed HTTP methods: HEAD

Path Parameters:

NameTypeRequirementDescription
identifierstring-The identifier of the customer (aka token)

GET Parameters:

NameTypeRequirementRequiredDescription
merchant_identifierstring-truemerchant identifier
  • Response  200
  • Body
    {
    "customer": {
        "stored_customer_email": "john.doe@raisenow.com",
        "token": "3851ca25fa22a21f1e68558eb33d9a88e8d1d551",
        "stored_customer_firstname": "John",
        "stored_customer_lastname": "Doe"
    }
}
  • Response  403
  • Body
    {'code': 403, 'message': 'You do not have the necessary permissions', 'errors': null}
  • Response  404
  • Body
    {'notfound' : '/vagrant/getunikepayment/app/../jsonresponsefiles/api/v1/customers/identifier/get/file-error.json'}

Update a Customer 

Update a Customer
/api/v1/customers/{identifier}

Other allowed HTTP methods: PUT

Path Parameters:

NameTypeRequirementDescription
identifierstring-The identifier of the customer (aka token)

POST Parameters:

NameTypeRequirementRequiredDescription
stored_[_a-z0-9]*string-falsecustomer parameter
merchant_identifierstring-truemerchant identifier
  • Response  204
  • Body
    {'code': 204, 'message': 'No Content', 'errors': null}
  • Response  403
  • Body
    {'code': 403, 'message': 'You do not have the necessary permissions', 'errors': null}
  • Response  404
  • Body
    {'code': 404, 'message': 'Not Found', 'errors': null}
  • Response  409
  • Body
    {'code': 409, 'message': 'Conflict', 'errors': null}

Payment 

Pay 

Pay
/epayment/api/step/{stepId}/merchant/{merchantId}

Other allowed HTTP methods: GET

Redirects to success_url, error_url or cancel_url. If 3d secure enabled, 3d secure window will be displayed before redirecting to the previous defined URL. If not all mandatory parameters are set, a form will be displayed.

Path Parameters:

NameTypeRequirementDescription
stepIdstringpayOnly pay supported yet
merchantIdstring-A merchant config (aka API Key).

POST Parameters:

NameTypeRequirementRequiredDescription
currencystring-truecurrency
amountstring-trueamount
error_urlstring-trueerror url
cancel_urlstring-truecancel url
success_urlstring-truesuccess url
payment_methodstringsms|vis|eca|amx|din|ezs|es|pfc|pef|pex|ddtrueSpecifies the payment method. In the glossary you find some further details about the allowed acronyms.
test_modestringtrue|falsetruetest mode
mobile_modestringtrue|falsetruemobile mode
languagestring-truelanguage
msisdnstring-falseValid cell phone number starting with +41
keywordstring-falseWhich SMS keyword should be used for the payment
sidstring\d+falseShortnumber of a SMS payment
css_urlstring-trueAbsolute URL to a CSS file, which should be used to style the credit card form. The CSS file will be loaded via e-payment platform and not directly from the origin. This mechanism should prevent cross-domain problems. Be sure to use absolute URLs within the CSS. If you want to load the CSS directly from origin, add the query parameter use_proxy to the URL and set it to false.
recurringstringtrue|falsefalseIndicates a recurring or one-time payment.
recurring_intervalstring-falseIf the payment is a recurring payment, the interval has to be specified. The interval is defined as in crontab except that minutes and hours may not be specified. Additionally, argument L is allowed to specify the last day of a month: L * *
stored_customer_emailstring-falseIf the payment is a recurring payment a valid customer’s email address has to be defined.
  • Response  301
  • Response  400
  • Body
    Url-parameter step needs to be set to 'pay'
  • Response  400
  • Body
    A valid (error_url | merchantConfigKey) needs to be provided
  • Response  400
  • Body
    merchantConfig is disabled
  • Response  400
  • Body
    the transaction_id parameter must be unique
  • Response  400
  • Body
    need to set a valid email address in stored_customer_email parameter
  • Response  400
  • Body
    no access to the specified payment_method
  • Response  400
  • Body
    recurring payments not available for requested payment_method
  • Response  400
  • Body
    parameter (payment_method | mobile_mode | immediate_execution | recurring_interval | subscription_token | test_mode | amount | currency | success_url | cancel_url) is invalid
  • Response  400
  • Body
    various messages depending on the payment provider
  • Response  404
  • Body
    A valid error_url needs to be provided

Payment Management 

Get Merchant Parameters 

Get Merchant Parameters
/epayment/api/transaction/merchant-params

Returns all Merchant Parameters

GET Parameters:

NameTypeRequirementRequiredDescription
transaction-idstring-trueepp transaction id
merchant-configstring-truemerchant config
  • Response  200
  • Body
    {
    "_stored_campaign_id": "",
    "_stored_campaign_subid": "",
    "_stored_rnw_purpose_text": "",
    "_stored_purpose": "zweck1",
    "_stored_customer_salutation": "mr",
    "_stored_customer_firstname": "john",
    "_stored_customer_lastname": "doe",
    "_stored_customer_email": "john.doe@raisenow.com",
    "_stored_customer_message": "",
    "_stored_customer_company": "",
    "_stored_customer_street": "",
    "_stored_customer_street_number": "",
    "_stored_customer_street2": "",
    "_stored_customer_pobox": "",
    "_stored_customer_zip_code": "",
    "_stored_customer_city": "",
    "_stored_customer_country": "CH",
    "_stored_foo": "bar"
}
  • Response  400
  • Body
    No merchant-config parameter defined
  • Response  400
  • Body
    No merchant-trx-id or transaction-id parameter defined
  • Response  400
  • Body
    Could not find transaction

Get Info 

Get Info
/epayment/api/transaction/status

Returns transaction information including status as json

GET Parameters:

NameTypeRequirementRequiredDescription
transaction-idstring-trueepp transaction id
merchant-configstring-truemerchant config
  • Response  200
  • Body
    {
    "transaction_id": null,
    "epp_transaction_id": "c2w8114132js65159",
    "created": "2014-10-14 07:39:19",
    "amount": 500,
    "currency": "chf",
    "payment_method": "VIS",
    "payment_provider": "datatrans",
    "user_ip": "10.189.247.2",
    "user_agent": "Mozilla\/5.0 (Macintosh; Intel Mac OS X 10_9_5) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/37.0.2062.124 Safari\/537.36",
    "http_referer": "https:\/\/mydomain.com\/",
    "mobile_mode": "false",
    "error_url": "https:\/\/mydomain.com\/error",
    "success_url": "mydomain.com\/success",
    "cancel_url": "mydomain.com\/cancel",
    "test_mode": "true",
    "language": "de",
    "card_holder_name": "test",
    "expy": "15",
    "expm": "12",
    "internal_return_executions": "1",
    "used_redirect_url": "https:\/\/dds-widget.getunik.net\/widgets\/lema\/ddswidget.html",
    "creditable": "true",
    "credited_at": "2014-10-14 07:40:06",
    "stored_customer_salutation": "mr",
    "stored_customer_firstname": "test",
    "stored_customer_lastname": "foo",
    "status": [
        {
            "created": "2014-10-14 07:39:19",
            "statusName": "new"
        },
        {
            "created": "2014-10-14 07:39:20",
            "statusName": "success_from_payment_provider"
        },
        {
            "created": "2014-10-14 07:39:20",
            "statusName": "success"
        },
        {
            "created": "2014-10-14 07:39:20",
            "statusName": "final_success"
        }
    ]
}
  • Response  400
  • Body
    No merchant-config parameter defined
  • Response  400
  • Body
    No merchant-trx-id or transaction-id parameter defined
  • Response  400
  • Body
    Could not find transaction

Add Merchant Parameter 

Add Merchant Parameter
/epayment/api/transaction/add-merchant-parameter

Adds a merchant parameter to the transaction identified by transaction-id and merchant-config aka ApiKey

POST Parameters:

NameTypeRequirementRequiredDescription
transaction-idstring-trueepp transaction id
merchant-configstring-truemerchant config
parameter-namestring-truename of the parameter
parameter-valuestring-truevalue of the parameter
merchant-trx-idstring-falsemerchant transaction id
  • Response  200
  • Body
    Parameter with name <Name> already exists
  • Response  202
  • Response  400
  • Body
    Could not find transaction
  • Response  400
  • Body
    No merchant-config parameter defined
  • Response  400
  • Body
    No transaction-id or merchant-trx-id parameter defined
  • Response  400
  • Body
    No parameter-name parameter defined
  • Response  400
  • Body
    parameter-name does not start with 'stored_'

Cancel 

Cancel
/epayment/api/transaction/cancel

Cancels a transaction

POST Parameters:

NameTypeRequirementRequiredDescription
transaction-idstring-trueepp transaction id
merchant-configstring-truemerchantconfig
  • Response  200
  • Body
    true
  • Response  200
  • Body
    false
  • Response  400
  • Body
    No merchant-config parameter defined
  • Response  400
  • Body
    No transaction id defined
  • Response  400
  • Body
    No transacition found
  • Response  400
  • Body
    MerchantConfig is disabled

Refund 

Refund
/epayment/api/transaction/refund/{merchantConfig}/{transactionId}/

Issues a full refund of the entire amount (only works for paypal and datatrans).

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring-A merchant config identifier (API Key).
transactionIdstring-An EPP transaction ID.
  • Response  200
  • Body
    {
    "status": "success",
    "original_epp_transaction_id": "c2niw14134xcrp10461",
    "refund_epp_transaction_id": "c20q214134ubt68294"
}
  • Response  200
  • Body
    {
    "status": "error",
    "original_epp_transaction_id": "c2niw14134xcrp10465",
    "refund_epp_transaction_id": "c256p1413418c68427",
    "error_code": "04-72",
    "error_type": "datatrans: amount exceeded",
    "error_detail": "amount not valid."
}
  • Response  400
  • Body
    you need to define a valid merchant-config and transaction-id
  • Response  400
  • Body
    merchant-config is disabled

Partial Refund 

Partial Refund
/epayment/api/transaction/refund/{merchantConfig}/{transactionId}/{amount}/

Issues a refund of a specified amount (only works for paypal and datatrans).

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring-A merchant config identifier (API Key).
transactionIdstring-An EPP transaction ID.
amountstring-The ammount to refund or ‘0’ to use the full ammount of the original transaction.
  • Response  200
  • Body
    {
    "status": "success",
    "original_epp_transaction_id": "c2niw14134xcrp10461",
    "refund_epp_transaction_id": "c20q214134ubt68299"
}
  • Response  200
  • Body
    {
    "status": "error",
    "original_epp_transaction_id": "c2niw14134xcrp10465",
    "refund_epp_transaction_id": "c256p1413418c68427",
    "error_code": "04-72",
    "error_type": "datatrans: amount exceeded",
    "error_detail": "amount not valid."
}
  • Response  400
  • Body
    you need to define a valid merchant-config and transaction-id
  • Response  400
  • Body
    merchant-config is disabled

Send Money to Paypal 

Send Money to Paypal
/epayment/api/sendtoemail/{merchantConfig}/

Send money to an email address. PayPal Account has to be created.

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring--

POST Parameters:

NameTypeRequirementRequiredDescription
amountint\d+trueepp transaction id
receiverstring-truemerchant config
subjectstring-truemerchant config
currencystring2 digit iso codetruecurrency
test_modestringtrue|falsetruetest mode
  • Response  200
  • Body
    {
    "status": "success",
    "epp_transaction_id": "c2niw14134xcrp104sdd"
}
  • Response  400
  • Body
    invalid test_mode defined
  • Response  400
  • Body
    invalid amount defined
  • Response  400
  • Body
    invalid receiver email address defined
  • Response  400
  • Body
    invalid currency defined
  • Response  400
  • Body
    No merchant-config parameter defined
  • Response  400
  • Body
    No valid merchant-config parameter defined
  • Response  400
  • Body
    MerchantConfig is disabled
  • Response  400
  • Body
    {
    "status": "error",
    "error_message": "foo bar",
    "error_detail": "xy",
    "epp_transaction_id": "c2niw14134xcrp104sdd"
}
Search
/epayment/api/{merchantIdentifier}/transactions/search

Retrieves a list of transactions and meta data based on the defined filters and facets.
If sort, filters and facets parameters have to be used in an array whereas foreach filter an index has to be defined.
E.g. sort[0][order], filter[0][field_name], facets[0][name]

Path Parameters:

NameTypeRequirementDescription
merchantIdentifier---

Filters:

NameTypeRequirementDescription
langstringen|de|fr|itlanguage
pageint\d+which page (pagination)
records_per_pageint\d+specifies how many records per page
sort[0][field_name]string-name of the field to sort on
sort[0][order]stringasc|desc-
filters[0][field_name]string-name of the field/attribue, 'all’,or a comma separated list of fieldnames (‘all’ and comma seperated list is only for fulltext type)
filters[0][type]stringterm|range|date_range|fulltexttype of the search
filters[0][from]string-lower limit of the range
filters[0][to]string-upper limit of the range
filters[0][value]string-value to search for
filters[0][filter_group]int\d+defines the filter group a filter belongs to
facets[0][name]string-unique (per search) identifier for the facet
facets[0][field_name]string-name of the field/attribue
facets[0][type]stringterm|range|date_range|stats|histogram|date_histogram(statistic filters have no size,order or ranges)
facets[0][size]string-how many occurences, Description TBD (only for termFacet, for range facets size is equal the number of ranges)
facets[0][order]stringcount|term|reverse_count|reverse_term(only for term, ranges are unsorted)
facets[0][interval]string-interval for buckets for histogram facets
facets[0][timezone]string-the timezone offset i.e(+2:0) from GMT. (only for date_histogram)
facets[0][factor]string-a multiplication factor for date_histogram key_field (i.e if the timestamp is without millisecond then the factor should be 10000)
facets[0][key_field]string-key field for histogram and date_histogram
facets[0][value_field]string-value field for histogram and date_histogram
facets[0][ranges]string-Array of ranges (only for range/date_range)
facets[0][ranges[0][from]string-lower limit of the range
facets[0][ranges[0][to]string-upper limit of the range
  • Response  200
  • Body
    {
    "result": {
        "filters": [
            {
                "field_name": "payment_method",
                "type": "term",
                "value": "vis"
            },
            {
                "field_name": "created",
                "type": "date_range",
                "from": "2012.12.01",
                "to": "2012.12.1400: 00: 00"
            }
        ],
        "facets": [
            {
                "name": "amounts",
                "type": "term",
                "missing": 410,
                "total": 67594,
                "other": 15220,
                "terms": [
                    {
                        "term": 90,
                        "count": 32839
                    },
                    {
                        "term": 500,
                        "count": 8420
                    },
                    {
                        "term": 1000,
                        "count": 5600
                    },
                    {
                        "term": 2000,
                        "count": 2802
                    },
                    {
                        "term": 5000,
                        "count": 2713
                    }
                ]
            },
            {
                "name": "date_histogram",
                "type": "histogram",
                "entries": [
                    {
                        "key": 1262160000,
                        "min": 1262307584,
                        "max": 1262519759,
                        "mean": 1262393889.1451,
                        "count": 255,
                        "total_count": 255,
                        "total": 321910441732
                    }
                ]
            },
            {
                "name": "amount_ranges",
                "type": "range",
                "ranges": [
                    {
                        "from": 1,
                        "to": 10,
                        "min": 1,
                        "max": 6,
                        "mean": 3.2674418604651,
                        "count": 172,
                        "total_count": null,
                        "total": 562
                    },
                    {
                        "from": 11,
                        "to": 100,
                        "min": 11,
                        "max": 99,
                        "mean": 88.817308842886,
                        "count": 33428,
                        "total_count": null,
                        "total": 2968985
                    }
                ]
            }
        ],
        "transactions": [
            {
                "epp_transaction_id": "aslfjasf2384u24",
                "amount": 500,
                "currency": "chf",
                "payment_method": "vis",
                "created": "2012.12.1213: 22: 22",
                "merchant-config": "sjldkf342",
                "last_status": "final_succes",
                "stored_customer_lastname": "muster"
            }
        ],
        "additional_info": {
            "lang": "en",
            "page": 20,
            "total_pages": 120,
            "records_per_page": 50,
            "total_amount_chf": 12308,
            "total_amount_eur": 123,
            "total_amount_usd": 11
        }
    }
}
  • Response  500
  • Body
    internal server error

Reconciliation Statement 

Gets a ReconciliationStatement 

Gets a ReconciliationStatement
/api/v1/reconciliation-statements/{identifier}

Other allowed HTTP methods: HEAD

Gets a ReconciliationStatement.

Path Parameters:

NameTypeRequirementDescription
identifier---
  • Response  500
  • Body
    {'code': 500,'message': 'server error','errors': null}
  • Response  403
  • Body
    {'code':403,'message':'You do not have the necessary permissions','errors':null}
  • Response  404
  • Body
    {'code': 404,'message': 'ReconciliationStatement not found','errors': null}

Updates a ReconciliationStatement 

Updates a ReconciliationStatement
/api/v1/reconciliation-statements/{identifier}

Other allowed HTTP methods: PUT

Updates ReconciliationStatement crmc transfer status. Cannot be used to update reconciliation data.

Path Parameters:

NameTypeRequirementDescription
identifierstring-ReconciliationStatement identifier

POST Parameters:

NameTypeRequirementRequiredDescription
crmc_transfer_statusfloat-true-
crmc_transfer_detailstring-true-
  • Response  204
  • Response  403
  • Body
    {'code':403,'message':'You do not have the necessary permissions','errors':null}
  • Response  404
  • Body
    {'code':404,'message': 'ReconciliationStatement not found','errors': null}

Subscription 

Get Info 

Get Info
/epayment/api/subscription/info/{merchantConfig}/{subscriptionToken}/

Returns a json array containing information about a subscription (customer object inside the subscription is mistakenly json encoded)

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring-A merchant config identifier (API Key).
subscriptionTokenstring-An EPP subscription token.
  • Response  200
  • Body
    {
    "masked_cc": "424242xxxxxx4242",
    "interval": "01 00 L *\/3 *",
    "customer_token": "9d5d995eea5db2c6c43f81c621610d0dfabddsdfsf",
    "status": "active",
    "success_url": "https:\/\/test.org\/success",
    "cancel_url": "https:\/\/test.org\/cancel",
    "error_url": "https:\/\/\/test.org\/error",
    "payment_method": "vis",
    "test_mode": "true",
    "currency": "chf",
    "amount": "6000",
    "immediate_execution": "true",
    "language": "de",
    "mobile_mode": "false",
    "stored_campaign_id": "1234",
    "stored_campaign_subid": "1234",
    "stored_rnw_purpose_text": "purpose 1",
    "stored_purpose": "purpose1",
    "stored_recurring_interval": "quarterly \/ immediate",
    "payment_provider": "datatrans",
    "expm": "12",
    "expy": "15",
    "customer": "{\"stored_customer_street\":\"doe\",\"stored_customer_street2\":\"john\",\"stored_customer_zip_code\":\"1234\",\"stored_customer_city\":\"test\",\"stored_customer_message\":\"test\",\"stored_customer_donation_receipt\":\"on\",\"stored_customer_salutation\":\"mr\",\"stored_customer_firstname\":\"john\",\"stored_customer_lastname\":\"ggg\",\"stored_customer_country\":\"CH\",\"stored_customer_email\":\"john.doe@raisenow.com\",\"token\":\"9d5d995eea5db2c6c43f81c621fsdfsfd\"}"
}
  • Response  400
  • Body
    No subscription-token provided
  • Response  400
  • Body
    No merchant-config provided
  • Response  400
  • Body
    Invalid subscription-token provided
  • Response  500
  • Body
    Error in SubscriptionInfo

Cancel 

Cancel
/epayment/api/subscription/cancel/{merchantConfig}/{subscriptionToken}/

Cancels a subscription

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring-A merchant config identifier (API Key).
subscriptionTokenstring-An EPP subscription token.
  • Response  200
  • Response  200
  • Body
    Subscription already canceled
  • Response  400
  • Body
    No subscription-token provided
  • Response  400
  • Body
    No merchant-config provided
  • Response  400
  • Body
    Invalid subscription-token provided
  • Response  500
  • Body
    Error in cancelSubscription

Charge a subscription manually 

Charge a subscription manually
/epayment/api/subscription/charge/{merchantConfig}/{subscriptionToken}/

Charges a subscription regardless of the subscription interval

Path Parameters:

NameTypeRequirementDescription
merchantConfigstring-A merchant config identifier (API Key).
subscriptionTokenstring-An EPP subscription token.

POST Parameters:

NameTypeRequirementRequiredDescription
asynchronousboolean-falseif subscription should be charged asynchronously. If ommited ‘false’ is assumed.
  • Response  202
  • Body
    charge pending
  • Response  202
  • Body
    charge successful
  • Response  202
  • Body
    charge failed
  • Response  400
  • Body
    No subscription-token provided
  • Response  400
  • Body
    No merchant-config provided
  • Response  400
  • Body
    Invalid subscription-token provided
  • Response  500
  • Body
    Error while charging the subscription

Generated by aglio on 30 Jul 2015