API reference
api reference this section provides the api reference for the merchant onboarding service use the following base urls for sending api requests testing environment https //us-esapi stg mpay samsung com production environment https //us-esapi mpay samsung com retrieve all services retrieves all your services endpoint get /wallet/v1/partner/services request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site response codes code type message 200 ok response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 200 ok code field type description companyid string business account name available in your business account profile details on the samsung pay portal companyname string company name available in your business account profile details on the samsung pay portal services array array of services services serviceid string unique service id services servicename string service name services servicetype string service type the possible values are web online paymentw3cinapp online payment services servicestatus string service status the possible values are debugging service is in development and not yet released verifying service is pending samsung approval approved service is active and available for online payments blocked service is inactive and cannot be used example 200 ok response { "companyid" "b449a46cec871291a58ad2", "companyname" "samsung pay partner company", "services" [ { "serviceid" "b449a46cec634171a58ad2", "servicename" "wallet web online", "servicetype" "web online payment", "servicestatus" "approved" }, { "serviceid" "a889a46cec222171a58ad3", "servicename" "online payment sample", "servicetype" "w3c", "servicestatus" "approved" }, { "serviceid" "k892a46cec444171a58aa7", "servicename" "inapp payment sample", "servicetype" "inapp online payment", "servicestatus" "approved" } ] } retrieve service details retrieves the details of a specific service endpoint get /wallet/v1/partner/services/{serviceid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site path serviceid string required unique id of the service to be retrieved response codes code type message 200 ok response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 200 ok code field type description serviceid string unique service id servicename string service name servicetype string service type the possible values are web online paymentw3cinapp online payment servicestatus string service status the possible values are debugging service is in development and not yet released verifying service is pending samsung approval approved service is active and available for online payments blocked service is inactive and cannot be used locations array array of countries where the service is allowed, in the iso 3166-1 alpha-2 format csr string pem-encoded certificate signing request csr used by samsung pay to generate a client certificate this certificate enables samsung pay to encrypt payment data before sending it to your server the csr can be self-generated or obtained from your payment gateway pgid string unique id of the payment gateway used for the service pgname string name of the payment gateway used for the service merchants object array of merchants associated with the service merchants merchantid string unique merchant id, assigned by the payment gateway pg merchants merchantname string merchant name merchants mcc array array of merchant category codes mccs merchants domains array array of domains authorized for samsung pay payments example 200 ok response { "serviceid" "b449a46cec634171a58ad2", "servicename" "wallet web online", "servicetype" "web online payment", "servicestatus" "approved", "locations" [ "us", "es", "fr" ], "csr" "-----begin certificate-----miiert 2gawib=-----end certificate-----", "merchants" [ { "merchantid" "1111a46cec634171a58ad2", "merchantname" "best buy", "mcc" [ "1231", "2213", "2333" ], "domains" [ "www bestbuy com", "bestbuy com" ] }, { "merchantid" "1231a46cec634171a58ad2", "merchantname" "gmarket jelly case", "mcc" [ "1231", "2213" ], "domains" [ "www gmarket com" ] }, { "merchantid" "3452a46cec634171a58ad2", "merchantname" "target online", "mcc" [ "2333" ], "domains" [ "www target com" ] } ] } create a service creates a new service endpoint post /wallet/v1/partner/services request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site request body field type required/optional description servicename string required service name servicetype string required service type the possible values are web online paymentw3cinapp online paymentcurrently, only web online payment is supported locations array required array of countries where the service is allowed, in the iso 3166-1 alpha-2 format csr string required pem-encoded certificate signing request csr used by samsung pay to generate a client certificate this certificate enables samsung pay to encrypt payment data before sending it to your server the csr can be self-generated or obtained from your payment gateway pgid string optional unique id of the payment gateway used for the service if the field is not provided, the none default value is used pgname string optional name of the payment gateway used for the service, such as fiserv response codes code type message 201 created response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 302 invalid csr partner csr upload error 400 303 invalid pg pg id is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 400 503 invalid domains domain name is not available 400 504 invalid test account test account form is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 201 created code field type description serviceid string unique service id servicename string service name servicetype string service type the possible values are web online paymentw3cinapp online payment servicestatus string service status the possible values are debugging service is in development and not yet released verifying service is pending samsung approval approved service is active and available for online payments blocked service is inactive and cannot be used locations array array or countries where the service is allowed, in the iso 3166-1 alpha-2 format csr string pem-encoded csr used by samsung pay to generate a client certificate this certificate enables samsung pay to encrypt payment data before sending it to your server the csr can be self-generated or obtained from your payment gateway pgid string unique id of the payment gateway used for the service pgname string name of the payment gateway used for the service example request { "servicename" "wallet web online", "servicetype" "web online payment", "locations" [ "us", "es", "fr" ], "csr" "-----begin certificate-----miiert 2gawib=-----end certificate-----", "pgid" "a20293812321", "pgname" "fiserv" } 201 created response { "serviceid" "b449a46cec634171a58ad2", "servicename" "wallet web online", "servicetype" "web online payment", "servicestatus" "debugging", "locations" [ "us", "es", "fr" ], "csr" "-----begin certificate-----miiert 2gawib=-----end certificate-----", "pgid" "a20293812321", "pgname" "fiserv" } update service details updates the details of a specific service notethis operation updates the fields provided in the request, and keeps the omitted fields unchanged for example, to update the service name, include only the servicename field in the request endpoint put /wallet/v1/partner/services/{serviceid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site path serviceid string required unique id of the service whose details are to be updated request body field type required/optional description servicename string optional service name servicestatus string optional service status the possible values are debugging service is in development and not yet released verifying service is pending samsung approval approved service is active and available for online payments blocked service is inactive and cannot be used locations array optional array of countries where the service is allowed, in the iso 3166-1 alpha-2 format csr string optional pem-encoded certificate signing request csr used by samsung pay to generate a client certificate this certificate enables samsung pay to encrypt payment data before sending it to your server the csr can be self-generated or obtained from your payment gateway pgid string optional unique id of the payment gateway used for the service pgname string optional name of the payment gateway used for the service response codes code type message 200 ok response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 302 invalid csr partner csr upload error 400 303 invalid pg pg id is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 400 503 invalid domains domain name is not available 400 504 invalid test account test account form is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 200 ok code field type description serviceid string unique service id servicename string service name servicetype string service type the possible values are web online paymentw3cinapp online payment servicestatus string service status the possible values are debugging service is in development and not yet released verifying service is pending samsung approval approved service is active and available for online payments blocked service is inactive and cannot be used locations array array of countries where the service is allowed, in the iso 3166-1 alpha-2 format csr string pem-encoded csr used by samsung pay to generate a client certificate this certificate enables samsung pay to encrypt payment data before sending it to your server the csr can be self-generated or obtained from your payment gateway pgid string unique id of the payment gateway used for the service pgname string name of the payment gateway used for the service example request { "servicename" "wallet web online pg service" } 200 ok response { "serviceid" "b449a46cec634171a58ad2", "servicename" "wallet web online pg service", "servicetype" "web online payment", "servicestatus" "debugging", "locations" [ "us", "es", "fr" ], "csr" "-----begin certificate-----miiert 2gawib=-----end certificate-----", "pgid" "a20293812321", "pgname" "fiserv" } remove a service removes a specific service endpoint delete /wallet/v1/partner/services/{serviceid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site path serviceid string required unique id of the service to be removed response codes code type message 204 no content 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 404 103 service does not exist service doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response retrieve merchant details retrieves the details of a specific merchant associated with a service endpoint get /wallet/v1/partner/merchants/{merchantid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site header x-service-id string required unique service id path merchantid string required unique id of the merchant whose details are to be retrieved this id is assigned by the pg response codes code type message 200 ok response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 403 103 merchant not eligible merchant is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 404 104 merchant does not exist merchant doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 200 ok code field type description merchantid string unique merchant id, assigned by the pg merchantname string merchant name mcc array array of merchant category codes mccs domains array array of domains authorized for samsung pay payments example 200 ok response { "merchantid" "1111a46cec634171a58ad2", "merchantname" "best buy", "mcc" [ "1231", "2213", "2333" ], "domains" [ "www bestbuy com", "bestbuy com" ] } add a merchant adds a merchant and associates them with a service endpoint post /wallet/v1/partner/merchants request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site header x-service-id string required unique service id request body field type required/optional description merchantid string required unique merchant id, assigned by the pg merchantname string required merchant name mcc array optional array of merchant category codes mccs domains array required array of domains authorized for samsung pay payments response codes code type message 201 created response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 403 103 merchant not eligible merchant is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 404 104 merchant does not exist merchant doesn’t exist on samsung pay 409 101 merchant id duplicate merchant id is duplicate of what was registered on service 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 201 created code field type description merchantid string unique merchant id, assigned by the pg merchantname string merchant name mcc array array of merchant category codes mccs domains array array of domains authorized for samsung pay payments example request and 201 created response { "merchantid" "1111a46cec634171a58ad2", "merchantname" "best buy", "mcc" [ "1231", "2213", "2333" ], "domains" [ "www bestbuy com", "bestbuy com" ] } update merchant details updates the details of a specific merchant notethis operation updates the fields provided in the request, and keeps the omitted fields unchanged for example, to update the domains, include only the domains array in the request endpoint put /wallet/v1/partner/merchants/{merchantid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site header x-service-id string required unique service id path merchantid string required unique id of the merchant whose details are to be updated this id is assigned by the pg request body field type required/optional description mcc array optional array of merchant category codes mccs domains array optional array of domains authorized for samsung pay payments response codes code type message 200 ok response body 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 102 test user not eligible test user is not eligible to company 403 103 merchant not eligible merchant is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 404 104 merchant does not exist merchant doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response response body for the 200 ok code field type description merchantid string unique merchant id, assigned by the pg merchantname string merchant name mcc array array of merchant category codes mccs domains array array of domains authorized for samsung pay payments example request { "domains" [ "www bestbuy com", "bestbuy com", "https //bestbuy com" ] } 200 ok response { "merchantid" "1111a46cec634171a58ad2", "merchantname" "best buy", "mcc" [ "online shop", "offline shop" ], "domains" [ "www bestbuy com", "bestbuy com", "https //bestbuy com" ] } remove a merchant removes the association between the merchant and the service endpoint delete /wallet/v1/partner/merchants/{merchantid} request parameters parameter name type required/optional description header authorization string required basic authentication header containing the base64-encoded username and password provided by samsung, in the following format basic <base64-encoded username password>for example authorization basic am9objpozwxsbw== header x-partner-id string required name of your business account, as defined on the samsung developer site header x-service-id string required unique service id path merchantid string required unique id of the merchant to be removed this id is assigned by the pg response codes code type message 204 no content 400 101 missing data mandatory parameter {%s} does not exist 400 301 invalid data {%s} parameter value is invalid 400 501 invalid account information account is not available 400 502 invalid service information serviceid is not available 403 101 service not eligible service is not eligible to company 403 103 merchant not eligible merchant is not eligible to company 404 101 company doesn’t exist company doesn’t exist on samsung pay 404 102 account doesn’t exist account doesn’t exist on samsung pay 404 103 service does not exist service doesn’t exist on samsung pay 404 104 merchant does not exist merchant doesn’t exist on samsung pay 500 100 internal server error samsung pay server internal error 503 100 service unavailable server is currently unable to handle the request due to a temporary overloading or maintenance of the server the implication is that this is a temporary condition, which will be alleviated after some delay if known, the length of the delay may be indicated in a retry-after header if no retry-after is given, the client should handle the response as it would a 500 response